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Introduction 



The V-System is a message-based distributed operating system designed primarily for high-performance 
workstations connected by local networks. It permits the workstation to be treated as multi- function 
component of the distributed system, rather than solely as a intelligent terminal or personal computer. 
Ultimately, it is intended to provide a general- purpose program execution environment similar to some 
degree to Unix. The programs are intended to interact with each other, and with programs running on 
traditional timesharing systems, to produce an integrated distributed system. 

1.1. The User Model 

One of die most important functions for the workstation is to provide state-of-the-art user interface support. 
In particular, the workstation should function as a from end to all available resources, whether local to die 
workstation or remote. To do so, the V-System adheres to dircc fundamental principles: 

l.Thc interface to application programs is (reasonably) independent of particular physical devices or 
intervening networks. 

2. The user is allowed to perform multiple tasks simultaneously. 

3. Response to user interaction is fast. 

In addition, facilities arc being developed to permit a consistent interaction discipline across applications. 

When die user boots his workstation he may communicate with one of two entities: an executive or the view 
manager. The user executes commands (application programs) from within an executive, which is the 
equivalent of a Unix shell or Tops-20 Kxi:c. The applications may run local to die workstation or remote. 
They may be written with die particular workstation in mind, or run in 'Terminal emulation" mode. They 
may require I/O modalities other than traditional text, namely, graphics. 

Bach application may be associated with one or more separate, device-independent virtual graphics 
terminals (VGT). A VGT may be created by the user (via die view manager) or by die activity itself, luich 
VGT may be used to emulate either a page-mode VT-100 terminal or a 2-dimcnsional raster graphics 
terminal. 

When die user wishes to initiate a new application concurrent with existing applications, he must first create 
a new VGT, with an associated executive. To do so, the user communicates with die view manager. The 
executive serves as a command interpreter from which the desired activity may be initiated. The user can 
create a new executive, with VGT, at any time, asynchronous to any existing activities. When a particular 
activity requires additional virtual terminals, it is Tree to create them. These VGTs will be deallocated when 
the activity terminates, whereas VGTs created by die user may only be deallocated by the user. 

Virtual terminals arc mapped to the screen when and where the user desires. Each such mapping is termed 
a view. When an activity creates a new VGT, it prompts the user to specify the default view. Thereafter, the 
user may create as many additional views as he wishes. To some extent, he may manipulate views of die same 
VGT independent of all other views of that VGT, for example, pan or zoom. All VGT management is 
performed via the view manager. 
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1 .2. The System Model 

The V-Systcm adheres to the server model: The world consists of a collection of resources accessible by 
clients*- and managed by servers. A server defines the abstract representation of its rcsource(s) and the 
operations on this representation. A resource may only be accessed or manipulated through its server. 
Because servers arc constructed with well-defined interfaces, the implementation details of a resource arc of 
concern only to its server. Note that a server frequently acts as a client when it accesses resources managed by 
other servers. Thus, client and server arc merely roles played by a process or module. 

Clients and servers may be distributed throughout die (intcr)nctwork. By default, access to resources is 
network transparent; a client may access a remote resource with the same semantics as it accesses a local 
resource. The result is an environment in which clients may communicate with servers without regard for the 
topology of the distributed system as a whole. However, we do not intend that a client cannot determine or 
influence the location of a particular resource, rather that a transparent mechanism is available. Moreover, we 
allow for clients and servers that were not written with network-transparent access in mind. 

Logically, then, die V-Systcm consists of a distributed kernel and a distributed set of server processes. A 
standard program environment is defined, the principal instance of which is the C program library. The C 
library includes runtime support for standard C and UNIX-like library functions to facilitate the porting of 
existing C programs. 

1 .2.1 . The Distributed Kernel 

The distributed kernel provides network-transparent interprocess communication based on synchronous 
message-passing. It consists of the collection of kernels resident on the participating machines. The host 
kernels may be implemented at a base level (as on the Sun workstation) or a guest level (as under Vax/Unix). 
The host kernels arc integrated via a low-overhead inter-kernel protocol that supports transparent interprocess 
communication between machmes. 

1.2.2. Servers 

Servers include: 

virtual graphics terminal server 

Provides all terminal management functions. One per workstation. 

Internet server Provides A Kiw Internet IP/TCP support 

pipe server Provides asynchronous, buffered communication facilities similar to Unix pipes. 

team server Provides team creation, destruction, and management One per workstation. 

exception server Fields process exceptions and dispatches them to registered handlers, such as debuggers. 
One per workstation. 

storage server Provides disk storage. 

device servers) Interfaces to ;i specific physical device, such as the console, mouse, serial line, or disk. 

local name server Provides locally defined character string names for (possibly) remote resources. One per 
workstation. 



*A client is a program requesting access to a resource, typically on behalf of a human user. 
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1.3. The Application Model 

Using the kernel well requires understanding the model of processes and messages that the kernel provides, 
and how they are intended to be used. Processes represent logical activities within the application. They are 
intended to be sufficiently inexpensive to allow the use of multiple processes to achieve the desired level of 
concurrency, in particular, multiple processes may share the same address space or learn, to facilitate fine- 
grain sharing of code and data. A team must be entirely contained on a single machine. 

Processes can be dynamically created and destroyed. When a process is created, it is assigned a unique 
process identifier that is used subsequently to specify that process. 

Synchronous message-passing facilitates communication between processes that looks to the sender like a 
procedure call. That is, the sender blocks until a reply to his request is received. Greater flexibility is 
provided to the receiver to allow scheduling of requests. Messages arc addressed to the process identifier of 
the recipient; there is no concept of a mailbox or port distinct from a process. 

Messages arc short and fixed-length. To facilitate transfer of large amounts of data, a separate data transfer 
facility is provided. Specifically, a process can pass, in a message, access to an area in its team space. This 
facility follows the procedure paradigm in being used primarily to access what arc logically "call-by- 
rcfcrcnce" parameters. Synchronization between the two processes involved in the data transfer is guaranteed 
by virtue of the fact that the recipient will not reply to die sender (and hence awaken him) until the transfer is 
complete. 

The kernel implements a low-level naming service that provides efficient access to server processes. A 
process can register its process identifier as corresponding to a particular logical process identifier. Clients can 
subsequently query the kernel as to the process identifier corresponding to a specific logical process identifier. 

Process scheduling is strictly priority-based. The effective priority of a process is the sum of its process 
priority, which is defined and fixed when the process is created, and its team priority. Team priorities can be 
dynamically varied by a server process to provide time-sliced scheduling. 

1.4. Outline 

The remainder of this manual consists of five parts: 
Part 1 Coimrnands: describes the user interface and available application programs. 

Part 2 Program Kim'romncnt: defines the V-Systcm program environment in terms of the 

existing C program library. 

Part 3 Servers: defines the standard I/O protocol and presents the server interfaces. 

Part 4 Kernel: describes the distributed kernel. 

PartS Appendices 

Any pari of the V-System may change without notice. Therefore, this documentation should be regarded as 
advisory. 
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Part I: 
Commands 
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— 2 — 
Using the V Executive 



2.1. Introduction 

The V executive is the part of the V system that accepts user commands from the keyboard and causes them 
to be executed. It corresponds to the Unix shell or Tops-20 Exec. There arc currently several versions of the 
executive, including two called exec and vgtsexec.- The two versions differ only in their handling of terminal 
I/O. The exec program runs a single executive, which uses the kernel console device, while the vgtsexec uses 
the Sun Virtual Graphics Terminal Service to provide any number of simultaneous execs. Although initially 
the vgtsexec provides one executive, the user can create and delete executives using the Exec 
Control command of trie view manager, described in the next chapter. 

'ITic basic operation of the executive is to read command lines and execute commands. The first field on a 
command line is the command name; the rest arc arguments to be passed to the command. Fields arc 
separated by spaces. A command name can be a built-in exec command, the name of a file containing a 
program compiled to run under the V system, or die name of a program to be run on a server, such as Unix. 
The executive provides a simple search path mechanism for commands. It looks first for a V program in die 
current context (i.e., directory), next in the current [bin] context, and finally in the [public] context. If it still 
cannot find it, it will try to execute the command remotely, on the server that is providing your current 
context. 

The executive waits for each command to exit, unless the last field on the command line is die single 
character &. In this case, the command runs in the background, while die executive continues to accept 
commands from die keyboard, in the vgtsexec, dicrc is a view manager option to terminate a program 
running in the foreground, but the plain exec currently provides no way to do this. A program running in the 
background may be terminated using die destroy command (see chapter 4). 

Other exec features arc described in section 2.7. 

2.2. Running the V Executive 

When you come up to an idle Sun workstation, it may be in one of several states. If die screen is blank, it is 
probably running V, but idle. The VGTS blanks die screen on idle workstations after a few minutes of 
inactivity. Move the mouse slightly or press any key on die keyboard to restore die display. A previous user 
may have left one or more of his sessions (sec below) active. The command 

logout 

will terminate them all and get you off to a fresh start. 

If die workstation is running some other program, dead, powered down, or the like, it will be necessary to 
reboot it, as described in the following paragraphs. 

There arc several brands of Sun workstation in existence, and booting procedures vary depending on the 
brand. The two major kinds arc those made by Cadlinc, which arc black, and those made by Sun 
Microsystems (SMI), which arc white. Many other computers based on the same 68000 CPU board may also 
run the V system, but details may be different. 



%cc section SI:R VERLvXEC for a description of the serverexec, which is used only on dedicated server machines. 
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A Cadlinc workstation in a random state can be reset to the PROM monitor by typing 
<crRL><SiurrxBRi-AK>, pressing die reset button, or (in desperation) power-cycling the workstation. It is best 
to try pressing the comma key on a Cadlinc's numeric keypad before resetting it If the V kernel is active at 
diat point, this key instructs it to turn off die mouse, necessary for proper operation of the prom monitor. 
Otherwise, you may have to power cycle the workstation or keyboard to regain control. 

On the SMI workstation, hold down erase EOF (White Keyboard) or Sirr-UP (Black keyboard) and hit the 
"A" key. There is no reset button on SMI workstations, and the SMI mouse does not need to be shut off. 

Suns that have an ordinary terminal as their console can usually be brought into the PROM monitor by 
hitting the terminal's BREAK key. Sometimes there is a reset button or switch attached. 

It is always necessary to reset the workstation by pressing the reset button or using the Sun monitor's kl 
command before running me V kernel. On SMI Suns, die kl command destroys the type font used by die 
PROM monitor to draw characters on the display, but this is restored by the. next b command. You can also 
use k2 on SMI Suns, which repeats die power-on diagnostics and thus takes much longer dian kl, but docs 
not destroy die font 

To run the V executive on a Sun workstation, reset the workstation and type the command 
n V 
to the Sun monitor. (Use b instead of n on SMI Suns.) If your Sun has a frame buffer, this command loads 
die vgtscxec, or a small version of the vgtsexec if you have 256 Kbytes of memory or less. If you have no 
frame buffer, die n V command loads the plain exec. You can force the plain exec to be loaded by typing 

n VV 

to die monitor. 

Both V and VV are special versions of the Vload program, "hardwired" to load a particular command. Sec 
chapter 12. 

2.3. Contexts and the Local Name Server 

A context in the V system is a generalization of the directories provided by other systems such as Unix. 
F.ach process (and thus each executive) has its own current context. A filename is normally interpreted in the 
current context, unless it begins with a square bracket ('['). Any filename that begins with a square bracket is 
sent to the local name server, which interprets the part of die name in brackets, dien forwards the request off 
to the specified context. Kor example, 

[diab1o]/usr/fnes 
means the name /us r/f11 os is to be interpreted in the context named [dlablo]. 

The local name server predefines several context names, and others arc defined by die login program and 
die executive. Users can define their own local names using the define and undefine commands. The 
command 

listdir [context] 
lists die local context names currently defined. 

2.3.1 . Changing the Current Context 

The cd (change directory) command can be used to change the current context for an exec. The command 
format is 

cd pathname 
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The pathname is interpreted in the (previous) current context. If the pathname is omitted, [homel is assumed 
(sec section 2.4.1). When an exec is created, its current context is set to die current value of [home]. 

2.3.2. Getting Context Names 

The context or pwd command wilt print a name for a context. It tries to find the most informative of the 
possible ways of naming the context. The command format is 

context pathname 

Tf the pathname is omitted, the command prints a name for the current context. This is the most common 
use. 

2.3.3. Defining and Undefining Names 

The command 

define name I name2 ... nameN oldname 

or 

define name I name! ... nameN -Ip logicalpid 

defines local names [name!] through [nameN] to refer to the same context as the current value of oldname or, 
if the "-lp" option is used,, to refer to die context corresponding to the supplied logical pid. (System logical 
pids arc defined in <Vcnviron.h>.) Brackets arc optional on name! through nameN, while oldname is 
interpreted in the current context unless surrounded by brackets. Any previous meanings for name I through 
nameN arc lost. 

The command 

undefine name I name2 ... nameN 
removes any existing local definitions of [name I] through [nameN], Brackets arc optional on these names. 

2.4. Sessions 

The V system uses the concept of a session to provide a relatively secure form of file access over a local 
network. To gain access to tiles on a host machine, it is necessary to create a session on that machine, by 
providing a valid user name and password to a server process running on the host. The session created has 
that user's file access permissions, so the existence of a V server on a machine does not add any additional 
complications to security or create any new security holes. Both the server prwess and the session it creates 
appear as ordinary V processes which can send and receive messages using the distributed V kernel 
interprocess communication protocol. 

2.4.1. Login 

The login command is used to create sessions. The command format is 

login hostname sessionname 

where both the host name and session name arc optional. If the host name is omitted, the login program will 
prompt for it. If the session name is omitted, it defaults to be the same as die host name. 

The login program always prompts for a user name and password. The password is not echoed when typed. 
An error message will be printed if the session cannot be created, or the user had an incorrect name or 
password. 

The login program registers the user's home directory on the newly created session with the local name 
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server. Thus after a 

login diablo 
command, the name 

[d tab To] paper s/nam1ng.mss 
refers to die file papers/nami ng .mss under the user's home directory on die host named diablo. 

The login program defines the local name [home] as an alias for die user's home directory on the last session 
created, and die local name [bin] as an alias for the V public directory on die host providing that session, if it 
maintains one. 

After the login command is run, the exec automatically changes its current context to the new value of 
[home]. Remember that diis docs not change die current context for any other process, including any of the 
other execs that may be running on the workstation. 

2.4.2. Logout 

'Hie logout command is used to terminate sessions. The command format is 
logout session name . . . 

where die session names arc optional. If one or, more names arc given, each of the named sessions is 
terminated. If no names are given, all sessions known to the local name server arc terminated. After it 
finishes, die logout command prints a count of die number of sessions logged out. If a session name was 
given and no such session was found, an error message is printed. 

Logging out a session can cause the current contexts of one or more processes on the workstation, the name 
[home], and/or die name [bin] to become invalid. Kxcculivcs try to recover from this situation, but other 
programs may not be able to. Do not log out a session if some program on your workstation is still using it 

2.4.3. Accessing Files Without a Session 

For convenience, the V servers provide a way of accessing a certain limited set of files without first creating 
a session. Any of the programs kept in die standard V public directory may be run without creating a session. 
The name (public! is predefined by die-local name server to refer to diis service. 

On a workstation with no sessions in existence, the names [home] and (bin| arc normally both defined to 
equal [public]. The current directory of the first exec created when V is booted is also set to [public]. 

The name [public] has die special property that it is mapped to a logical process id (and well-known context 
id) instead of a specific server process. Itach time the name is used, it is automatically mapped to a currently 
existing server, the one which responds first to die name server's GctPid request Other names which arc 
defined to equal [public], as mendoned above, get its current value when they arc defined; they do not cause a 
GctPid on each use. 

2.5. Remote Program Execution on a Session Server 

If the executive fails to find an appropriate load file for a command, it will attempt to execute the command 
on the server providing its current context by invoking the /execute program. Thus, for example, when a V 
server on Unix is providing the current context, all die standard Unix commands like fmger, make, or Is are 
available. The output of die Unix command is printed on the standard output file. 

You can also supply input to remote commands. The character echoing and line editing on this input arc 
done on the workstation, not by die session server machine. You can type 

control-t c [return] 
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to send an end of file to the remote command, or 

control-* e [return] 
to cause the remote command to exit Type control -t twice to send a single control -+ character to the 
remote command. 

Since both the input and output arc done through pipes, and input is a line at a time, many Unix programs 
which expect to be run on tty devices (such as emacs, telnet, more, etc.) do not work in this mode. Such 
programs can only be am by logging in to the Unix machine, perhaps using one of die V telnet programs to 
connect to it (see chapter 4). 

The V servers do not provide execution of Unix commands without a session. If the executive tries to 
execute a Unix command in the [public] context, die V server returns an "Illegal request" error. 

2.6. Remote Execution on a Designated V Host 

A command can also be executed remotely by explicitly designating another host. This is done by 
specifying the process id of the team server for the host on which the command is to be run. (Syntax details 
arc described in 2.7.6.) Remote execution of this type is transparent to die user in that I/O is still directed to 
the local host. 

2.7. Executive Facilities for Command Specification and Modification 

The executive provides various facilities for specifying and editing command lines and for redefining 
various aspects of command execution. The syntax and semantics of each is described below. 

2.7.1 . Line Editing Facilities 

Command lines can be edited with Emacs-stylc line-editing keys. More specifically, the following editing 
commands arc available. CTRL-x means striking the Control key and the x key simultaneously; BSC-x 
means striking the Kseapc key and then die x key. 

CTRL-a Move cursor to beginning of the command line. 

CTRL-b Move cursor back one character. 

CTRL-c Kills the Break Process, usually the command running in the current executive. 

CTRL-d Delete character under the cursor. 

CTRL-c Move cursor to the end of the command line. 

CTRL-f Move cursor forward one character. 

CI'RL-g Abort the command. The line editor will pass the command line, followed by a Cf'RI ,-g, to 

die client program, which is responsible for detecting the Cl'RL-g and reacting to it. 

CI'RL-h Delete the character before the cursor. Equivalent to the DHL key. 

CTRL--k Delete the command line from the cursor to the end of the line. 

CI'RL-t Transpose the two characters preceding die cursor. 

CI'RL-u Delete die command line up to the cursor. 

Cl'RL-w Delete- from the cursor to the beginning of the current word. 
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CTRL-z Causes an End of File indication to be sent to the application reading the line. This will 

terminate the Executive if no application is running. 

ESC-b Move cursor to the beginning of the current word. 

ESC-d Delete from the cursor to the end of the current word. 

ESC-f Move cursor past the end of the current word. 

ESC-h Delete from the cursor to the beginning of die current word. Same as CTRL-w. 

Printing characters are normally inserted at the cursor. Commands are submitted to the executive for 
execution by hitting carriage return. This can be done regardless of where in the command line the cursor is. 

2.7.2. Command History References 

The executive also maintains a history of the last 20 command lines that the user has typed in. These 
command lines may be referenced by typing die character I immediately followed by a prefix of the desired 
command line. Thus if the command line 

cp /ng/ng/V/cmds/exec/exec.c /tmp/exec.c 
was typed in, then it can be referenced by typing (for example) 

tcp 
If a non-unique prefix is specified then the most recent command with that prefix is taken. Another special 
form of reference is 1 1 , which references the previous command line. 

When a command line is referenced it is redisplayed for further line editing and verification. Thus in the 
previous example typing 

lep i 

will cause the executive to display 

cp /ng/ng/V/cinds/exec/exec.c /usr/sun/Vboot/exec.c 

with die cursor sitting at the end of the line. The user can then hit carriage return to rccxecutc the line or can 
edit it first to derive a new command. 

The command history will cause the executive to list the command lines it has stored in its history record. 
The most recently executed command will be at the bottom of the list. 

2.7.3. Command Aliases 

Command names can be aliased by means of the alias command. Thus, for example, typing 
alias e ved 

will cause the command name "c" to be replaced by "ved" in subsequent command lines. Note that aliasing 
is done only for command names and not for command arguments. (Remember that the command name is 
the first word of a command line.) 

Aliases specify a string for replacement of the alias word. Thus one can create aliases such as 

alias test /ng/mmt/test/testcopy -d 

Then typing something like 

test filel file2 

will cause the command 

/ng/mmt/test/testcopy -d filel file2 
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to be submitted to the executive for- execution. 

A list of all defined aliases can be obtained by typing alias without any arguments. The command unalias is 
used to remove an alias definition. Specifying a new alias definition for a command name simply replaces the 
old one. 

2.7.4. I/O Redirection and Pipes 

I/O redirection and specification of pipes between two (or more) commands is done using the same syntax 
as is used by the Unix shells. Thus input can be redirected to come from a file by specifying 

and < file 

and output can be redirected to a file by specifying 

cmd > file 

cmd » file 

The latter form specifics that the output should be appended to the flic whereas the first form will overwrite 
any data already existent in the file. Krror output can be redirected by specifying >? or »?. The forms >& 
and »& redirect both standard output and standard error to the same file. 

A special form of redirection is available for bidirectional files, such as the serial lines available on Suns. 
Specifying 

cmd <> file 

causes the command's input and output to be redirected to the same file. To be precise, the file is opened in 
FCRKATE mode, and standard output is redirected to the instance thus created. Standard input is redirected 
to come from an instance whose id is equal to the output instance id plus I. This matches a convention used 
by several V-Systcm I/O servers. The form <>& also redirects standard error to the same instance as standard 
output. 

Pipes can be set -up between several commands by separating them with a | on die command line.. Thus, 
foir example, die command line 

cmdl | cmd2 \ cmd3 •> log 

will create two pipes and redirect I/O so that the output of cmdl will be used as the input to cmd2, the output 
of cmd2 will be used as Uic input to cmd2, and the output of cmd2 will be redirected into the file log. 

All the special characters described above must be surrounded by spaces for die executive to recognize 
them. Redirection clauses must appear after all arguments to be passed to Uic command. 

2.7.5. Concurrent Commands 

Commands can be specified as being concurrent by including an & at the end of the command line. This 
causes Uic executive to return immediately to the user for another command rather than waiting until the 
current command completes. Also, while nonconcurrcnl (foreground) commands are terminated if their 
executive is deleted, concurrent (background) commands will continue even if Uic executive Uiat initiated 
Uicm goes away. 

The & must be preceded by a space for the executive to recognize it 
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2.7.6. Execution of Commands on Another Host 

Commands can be designated to execute on another host by including 
TeamServerPid 
at the end of the command line. (Note: an & can be specified in addition to this.) Here TeamServerPid is the 
hexadecimal process id of the team server residing on the remote host where the command is to be executed. 

Remote execution is transparent to the user in that the I/O of the command is still directed to the local host 
and will be displayed in the same manner as if the command were executing locally. 

The <§ sign must be surrounded by spaces for the executive to recognize it. The remote execution clause, if 
present, must follow all arguments to the command (but may be intermixed freely with redirection clauses). 



Using the hex pid is a temporary measure until some form of host name service is available. 
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— 3 — 
The View Manager 



The view manager provides an interface between the user and the VGTS. The programmer's interface to 
the VGTS is described in the V-Syslem Programming Environment Manual and the internal structure of the 
VGTS is described in the V-System Servers Manual. "Hie program creates SDFs and objects within them, and 
associates these objects with Virtual Graphics Terminals (VGTs). Through the view manager, the user maps 
these VGTs onto physical screens, and manipulates the resulting views. The VGTS multiplexes both the 
output devices (the screen) and the input devices (keyboard and mouse) among all the programs that use 
them. The VGTS is no longer physically integrated with the executive, although the view manager docs 
provide an interface to the exec server. The line-editing functions described in section 2.7.1 arc provided by 
the VGTS, like any terminal agent 

3.1 . VGTS Conventions 

Virtual terminals appear .as white overlapping rectangles on the screen, with a black border and a label near 
the top edge. There is at most one virtual terminal (usually a pad, or text-only virtual terminal) that is getting 
input from the keyboard, along with possibly other virtual terminals getting input from the mouse. This is 
indicated by a flashing black box for a cursor in the text virtual terminal, and a black label on all the views 
that arc accepting mouse input Note that all virtual terminals arc always active in the sense that any 
application may run or change the display in any virtual terminal at any time independent of tilts selection; it 
only applies to input 

Clicking the left or middle button of the mouse in a non-selected virtual terminal will cause it to be selected 
for input Views of selected pads will be brought to die top. The input pad can be changed by using control 
up-arrow (octal 036) followed by a single command character. The only command characters interpreted by 
the VGTS arc 1-9 to select the given pad for input 

'ITicrc arc a few conventions for using the mouse with the VGTS. A "Click" consists of pressing any 
number of buttons down and releasing them at a certain point on the screen. While the buttons arc down 
there may be some kind of feedback, like an object which follows the cursor. The click is usually only acted 
upon when all the buttons arc released, so if you decide you have made a mistake after pressing the buttons 
you can slide the mouse to some harmless position before releasing the buttons. Molding all three buttons 
down is also interpreted as a universal abort by most programs and the view manager. The click event is sent 
to the program associated with the view in which the event occurred (through its VGT). 

When a V-Systcm program requests the creation of a pad, the cursor will change to the word "Pad". At this 
point hold down any button, and an outline of the view which will be created will be tracked on the screen. 
Position the view where desired, and let go of the button. 

3.2. View Manager Menus 

The view manager menus can always be invoked by moving the cursor to the grey background area or any 
virtual terminal not getting input (except in the banner area) and pressing the Right button. The following 
commands arc available from the view manager menus: 

Create View Creates another view of an existing VGT. Move the cursor to die desired position of any 

one of the four corners for die new viewport. Hold any button down, and move the cursor 
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to the diagonally opposite corner. An outline of the new view will follow the cursor as it 
moves with the button clown. Let the button up, and then point at the VGT that you 
would like to sec with the left or middle buttons, or hit the right button and select the VGT 
from the menu. Normally only used with graphics VGTs. 

Delete View Click one view which is removed from the screen. Warning: if you delete the last view of 

a VGT, it does not destroy the VGT or the process associated with it. You can still create 
views of the VGT by using the right button menu in the Create View command. 

Move Viewport Press any button to select a viewport to move. While the button is being held down, die 
outline of the viewport will move, following die cursor. Lift up the button at the desired 
position. None of the other view parameters are changed. A shortcut to -this function is 
obtained by pressing the middle button while pointing to the banner of die desired 
viewport. The viewport outline will follow the cursor until the middle button is released. 

Make Top Brings the view to the top, potentially obscuring other views. A shortcut to this function is 

obtained by pressing the left button while pointing to the banner of the desired viewport 

Make Bottom Brings Brings the view to the bottom, potentially making visible other views. A shortcut to 
this function is obtained by pressing the right button while pointing to the banner of the 
desired viewport. 

Kxec Control Selects a submenu to create another executive, destroy an executive (and die teams running 
in it), kill a program, or control paged output mode. When you arc creating an executive, 
the outline of the new pad will follow the cursor as you hold die button down. Lift the 
button up at die desired position, or press all dircc buttons to abort. A shortcut to die Exec 
Control menu is obtained by pressing both the middle and right buttons while the cursor 
points to the gray background or the display area of a viewport not requesting mouse 
information. 

Graphics Commands 

Selects another menu of commands that arc usually only applied to graphics views. These 
arc described below: 

Center Window Click the position that you want to become die center of the viewport. Hoes not change 
the position of the viewport on die screen, just die object within die view. Doing this to 
pads is almost always a mistake. 

Move Edges Push any button down next to an edge or corner, move that edge or corner to die new 

position, and let die button up. The edge outline should follow the cursor as long as you 
hold die button down. Docs not move the object being viewed relative to die screen. 

Move Edges + Object 

Similar to die previous command, but diis one drags the underlying object around with the 
moved edge or corner, while the previous command keeps it stationary with respect to die 
screen. 



Zoom 



Invokes a Zoom mode, indicated by a change in the cursor to die word "Zoom". You can 
get out of this mode in two different ways: First clicking the left or middle buttons when 
the cursor is inside a view of a pad returns from die view manager and selects that pad for 
input As a side cTfcct diat view is also brought to the top. Secondly, you can click the 
right mouse button. The cursor should change back to the normal arrow. 

The left and middle buttons in Zoom mode zoom out and in respectively. That is, the left 
button makes the object look smaller, and the middle button makes it look larger. You can 
remember diis because die "outer" (left) button zooms out, and the "inner" (middle) 
button 7.00ms in. A shortcut to this mode is available by clicking die middle and left 
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buttons at the same time while the cursor points to the gray background or the display area 
of a viewport not selected for input 

Expansion Depth Click to determine the view, then select the new expansion depth from the menu. Symbols 
will not be expanded more than this many levels into the hierarchy, fnstead they will be 
drawn as outlines with text for their names if there is room. The default expansion depth is 
infinity, so all levels will be normally expanded. 

Redraw Redraws all the views on the screen; necessary only during debugging. 

Toggle Grid Click once to aim the grid on if it is off, or off it is on in the view you select The grid dots 
are every 16 screen pixels, and always line up with the origin. 

Debug Enables lots of extra printouts, for maintenance use only. This command asks for 

confirmation, to discourage its accidental invocation. It will not turn on debugging unless 
the response begins with die letter y. 

A shortcut to the Graphics Commands menu is obtained by pressing both the left and right buttons while 
the cursor points to the gray background or the display area of a viewport which is not requesting mouse 
information. 

3.3. Paged Output Mode 

When paged output mode is on, the terminal agent stops writing to a pad when the pad fills up with output 
The terminal agent then displays the message "Type <spacc> for next page" and waits for the user to issue a 
command which unblocks the pad. This section describes the available commands. 

Most commands are optionally preceded by an integer argument k. Defaults arc in brackets. Stir(*) 
indicates that the argument becomes the new default 

<spacc> Display die next k lines [current page size] 

/, Z Display the next k lines [current page size]* 

<CR>, <! ,F> Display the next k lines [1] 

q, Q Throw away all output until the next time input is sent to the application program. 

s Skip forward A lines [1] 

S Skip forward to the last line 

f Skip forward k pages [I] 

F Skip forward to the last page 

<backspacc>, 1 )KI . Erase the last character of the numeric argument 

Repeat the previous command 

If the user types a character which is not a valid command, die character is treated as a normal input 
character. If line editing mode is on, the CTRL-c and Cl'RL-z commands (sec section 2.7.1) have dieir usual 
effect here. 
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3.4. MouseEscape Sequences 

Inside a pad, when connected to some host through a telnet program, the buttons have the following effect: 

Left Button Sends the sequence escape M <xXy> which positions the Emacs cursor at the position of 

the click. 

Middle Button Selects the clicked pad for input, and brings the view selected to the top. 

Right Button View manager menu, described in the previous section. 

Left+ Middle Buttons . 

Sends the sequence escape M <xXy> null which sets the Emacs mark to the clicked 

position. 

Left + Right Buttons 

Sends the sequence escape M <xXy> tW which deletes in Emacs from the mark to the 
clicked position. 

Middled Right Buttons 

Sends the sequence escape M <xXy> tY which inserts the kill buffer at the clicked position 

in Emacs. 

'ITic above escape sequences arc enabled by turning on the ReportEscSeq bit in the cooking mode of the 
virtual terminal. Sec the VGTS chapter of the library manual for more details. 

3.5. Mouse Emulation via the Keyboard 

For the benefit of hardware configurations without a working mouse, die VGTS can interpret certain 
keyboard escape sequences as mouse input. The VGTS will only intercept these escape sequences if they arc 
sent as a rapid buret of characters, as is the case when they are sent by pressing a function key. if die escape 
sequences arc typed manually, the VGTS will detect the space between characters and pass them through in 
die normal fashion. 

'Hie following is a list of die escape sequences used and the function keys with which dicy arc normally 
associated on an ANSI (VTlOO-stylc) keyboard. 

HSC ( A (ANSI Down Arrow) 

Move die mouse cursor down. 

ESC [B (ANSI Up Arrow) 

Move the mouse cursor up. 

ESC [C (ANSI Right Arrow) 

Move the mouse cursor to the right 

ESC [D (ANSI Left Arrow) 

Move the mouse cursor to die left. 

ESC OP (ANSI PEL) 

Toggle the value of the left mouse button. The new value of the left mouse button is 
displayed in die view manager window. 

ESC OQ (ANSI PR) 

Toggle the value of die middle mouse button. The new value of the middle mouse button 
is displayed in the view manager window. 

ESC R (ANSI PE3) 
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Toggle the value of the right mouse button. The new value of the right mouse button is 
displayed in die view manager window. 

ESC OS (ANSI PF4) 

Toggle mouse emulation mode. When mouse emulation mode is OFF, all escape 
sequences except for ESC O S (ANSI PF4) will be passed through -as normal, allowing the 
associated function keys to perform application-defined functions. The new state of mouse 
emulation mode is displayed in the view manager window. 

When the VGTS receives input from a "real" mouse, mouse emulation is permanently disabled. If your 
mouse fails, you must use the "newterm" command to create a new VGTS in order to use mouse emulation. 
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_4_ 
Command Summary 



4.1 . Workstation Commands 

The following briefly summarizes the currently available commands for V. 



amaze 
biopsy 



bits 
boisc 



cd 
checkers 

clear 



A multi-person distributed game. Docs not (yet) run under the vgts. Sec chapter 10. 

Prints information about all the processes on the workstation, sorted by team. Several 
options arc recognized. The -1 option also includes the filename from which each team was 
loaded. (This generally makes the output longer than one screenful.) The -t option 
followed by a pid or the suffix of a team's filename will cause information to be printed 
only about the team associated with the pid or filename. More than one pid or filename 
can be specified - information for each will be printed. To obtain detailed information 
about one or more processes, invoke biopsy with just the pid(s) of the relevant process(cs). 

A program for manipulating bitmaps and fonts. Sec chapter 9, and the online help file. 

Prints files on the Boisc laser printer. 

Several switches arc allowed, preceding the filenames: 

-r Print rotated, that is, in landscape (horizontal) mode. 

-n name Use name to label the output. If this option is not given, the "For user:" 
field is left blank. 

-b banner Use banner in the "File:" field instead of the filename. 

-h hostname Host name to use instead of "V-Systcm". 

-m mode Print mode. Possible modes arc 





Line printer (the default). For printing ordinary text 
files. 

DVI. For printing TcX output. 

Press. Not implemented. 

HP2680a. For files in HP2680a "spool file" format. 



•w 



File is in the Sail ("WAITS") character set instead of standard ASCII. 
(Line printer mode only). 



If no filenames arc given, boise reads its standard input 

Change directory: change the current context. 

Lets, you play a game of checkers against die workstation. This is also a good 
demonstration of the vgts' graphics capabilities. Sec chapter 10. 

Clears the pad. 
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context 

cp 
copydir 



dale 

date 

define 

debug 
destroy 

dopar 

doscq 

draw 
echo 
fcxecutc 

help 

intcrnctscrvcr 
iphost 

iptelnct 
iptn 



Prints an expanded name for the current context, or if a context name is given, for that 
context Also known as pwd (print working directory), by analogy with Unix. 

Copy the first file to the second file. 

Invoked as: 

copyd 1 P J'romdir todir 

copies the fromdir directory subtree to todir. todir must previously exist. New files arc 
created in a default mode, while the mode of existing files (being updated) is left alone. 

Distributed version of yet Another Layout Editor is a VLSI layout editor that provides 
graphics editing of SILT chip descriptions. Documented in a Stanford CSL Technical 
Report. 

Prints the date as maintained by the local workstation kernel, and as maintained by the 
session host. The kernel-maintained time on a workstation is set from a time server when 
the exec is started. The command date -s sets the local time to the network time. 

Defines one or more local names for a context. The first argumcnt(s) arc die new names to 
be defined. The last argument is a context name, specifying the value to be given to the 
new names. 

'Hie V debugger. Sec chapter 6. 

Takes the name of a team (or any suffix) as an argument, and send? a message to the team 
server asking it to destroy that team. If the argument begins with the characters Ox, it is 
taken as a process id, and that process is destroyed. 'Hiis is useful for killing processes run 
in the background. 

A program similar to doseq, except that it allows the executions of its command argument 
take place in parallel on different hosts. ITic program prompts for the names of hosts on 
which to execute the command (for each context). If"*" is entered, then the service server 
will select an 'arbitrary' available host. 

This program takes two string arguments: a list of context names, and a command to 
execute. The command is executed in each context in turn, doseq is often useful in 
makefiles, doniake is a synonym for doseq. 

An interactive drawing program that runs under the VGTS. See chapter 8. 

Echos its arguments. 

Force a command to be executed on the server providing the current context, as described 
in section 2.5. 

A program which prints out a little bit of information about the V system, he! p ? prints a 
list of topics on which help is available. 

A version of die Internet Server, as described in the V-Systcm Servers manual. 

If given a single host name as an argument, iphost lists all IP addresses corresponding to 
diat host If no argument is given, the IP address of the local workstation is printed. 

A multi-window IP/TCP telnet program using the VGTS. This program has a copy of the 
VGTS linked into it, so it is only useful under die bare kernel or the STS. Use iptn under 
the VGTS. 

IP/TCP-bascd telnet implementation. It can run under the STS, or in a VGTS window. A 
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listdir 

login 

logout 

ncwtcrm 



pagcmodc 



query 



rm 
serial 



destination host name or address may be given as a command argument; if none is given, 
ipin prompts for one. A host name is a string of non- white-space characters storting with a 
non-numeric character. A host address is a string of the form a.b.c.d, where a,b,c and d are 
decimal integers. Both names and addresses may be followed by a dot and a decimal port 
number (with no intervening spaces). 

While connected to a remote host, ipin recognizes a set of commands prefixed by ctrl-t. 
Ctrl-t ? prints a list of all such commands. 

After disconnecting from a remote host, ipin prompts for another host. To exit ipin, enter 
ctrl-c or ctrl-z in response to the prompt 

If there is no internet server on your workstation when ipin is loaded, it runs one in the 
background. The -1 flag inhibits loading a local server, instead looking for a public internet 
server running on another V hosL 

The -d flag enables debug mode. In this mode, all transmitted and received telnet protocol 
commands arc printed, and all received non-printable characters arc printed in an escaped 
notation. Debug mode can be toggled on and off by typing ctrl-t d while connected to a 
remote host. 

Lists the names defined in a context, and prints some information about each. If no 
argument is given, the current context is assumed. 

Command to start a session on a computer running a V server. 

Command that terminates sessions. 

Change terminal agents. Takes one argument, the filename of a new terminal agent to take 
the place of the existing one. All executives running under the old terminal agent arc 
destroyed; the new one will presumably provide means of creating a new one. For 
example, ncwtcrm sts replaces the vgts with the Simple Terminal Server, which docs no 
graphics but simply presents the workstation as an ascii terminal. If no argument is given, 
it defaults to "vgts". Warning: If the named program is not in fact a terminal agent, you 
will probably lose control of your workstation. 

Enable or disable paged output mode in die current executive. Takes one argument, which 
may have one of two values: "on" or "oil". When paged output mode is on, the terminal 
agent stops writing to a pad when the pad fills up with output. The terminal agent then 
displays the message "Type <spacc> for next page" and waits for the user to issue a 
command which unblocks the pad. The user interface for paged output mode is described 
in section 3.3. 

Prints out the result of performing various 'query' operations. In particular, query 
kernel prints the result of the QueryKernel operation, query conflg prints the 
contents of the workstation's configuration file, and query ethernet prints die result of 
querying the "ethernet" device, query ? lists the possible options. 

Takes one or more filenames as arguments, and removes each file. 

This program provides a full-duplex conversation between its standard input and output, 
and a device connected to one of die serial ports of die workstation. The argument is a 
device name, specifying the line to be opened. It defaults to [devkeJserialO if omitted. 
Names of die form fdcvicejserialn (with n a single digit) can be abbreviated by giving only 
the digit. If die serial line is connected to a modem or a terminal port on another 
computer, diis program allows die Sun to act as a terminal. The flag -b b1 trate can be 
used to specify the bit rate (baud rate) of die connection; it defaults to 9600 bps. 
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COMMAND SUMMARY 



show 



telnet 

testexccpt 

timckcrnel 

tn 



type 

undefinc 
ved 



Displays a .dv1 file or a .press file. It is driven from a menu in the invoking pad: by 
selecting die appropriate field, you can move around from page to page, with cither 
relative movement, absolute page number or the TcX generated \countO numbers. You 
can invoice it with show filename, or you can set the filename in the menu. You can 
"scroll" a page by pressing a mouse button inside the view, moving the mouse and 
releasing the button. It handles the TeX generated dv1 files pretty well, though 
magnification is ignored and some fonts are missing. Biggest problems: it only handles a 
small subset of press format, there arc no good scribe fonts for it, and it is a bit slow. 

A multi- window PUP-bascd telnet program using die VGTS. This program has a copy of 
the VGTS linked into it, so it is only useful under die bare kernel or die STS. Use /// under 
the VGTS. 

Simple interactive program for testing the exception server. 

Program to measure the time for Scnd/Rcccivc/Rcply kernel primitives. 

PUP user telnet program. It can be run under the STS or in a VGTS window. /// takes an 
optional argument specifying the host to connect to. While running, the following 
keyboard commands arc available: 



ctrl-t c 
ctrl-t d 

ctrl-t e 
ctrl-t o 

ctrl-t b 



Close die connection. 

Close the connection and delete the VGT, if created by tn. 
available when running with the VGTS.) 

Close all connections and exit from tn. 



(Only 



Create a new VGT and open another connection in it (Only available 
when running with the VGTS.) 

Create a big (48-linc) VGT and open another connection in it. (Only 
available when running with die VGTS.) 



ctrl-t ctrl-t Transmit a ctrl-t character. 

in is capable cither of using Uic raw Ethernet device on the workstation, or going through a 
local internet server. If there is a local internet server, tn must use it, since the kernel 
Kthcrnct device is single-user. I*vcn if there is no local internet server when tn is loaded, to 
be compatible with ipln, tn will load a local internet server and work through it if there is 
no public internet server elsewhere on die network diat could be used by iptn. To force tn 
to use the raw Ethernet device if it can, invoke it with die command line tn raw 
hostname. 

Only one copy of tn may be run on a workstation at one time. 

Type out one or more files on die terminal. Types a page- full and then' stops and waits for 
input. Pressing (SI»AC1-| brings up another page, while [RtTURNl brings up another line. 
Hit q or tC to quit 

Removes die definitions of one or more local context names. 

A text editor, similar to Emacs, which runs under the vgts. Described in chapter 7. 
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4.2. Commands on Session Hosts 

There arc also several useful commands that can be invoked on session hosts (usually a Vax/Unix system). 
Use these commands once you have logged into a machine through a telnet connection. Most of these 
commands also have versions that run locally on the workstation under the vgts, and the Unix versions can 
also be run remotely under the vgts, using the exec's remote execution feature (section 2.5). 

dale A version of the Yale layout editor that runs under the vgts. 

photo Reads and displays a ".sun" format raster file. 

silcdit A program which edits .SIL format files. SIL, a Simple Interactive Layout program, is a 

graphics editor- for logic designs and illustrations. 

silprcss A program which takes a .sil format file and produces a .press format file that can be 

printed on the Dover. 
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— 5 — 
Executive Control Commands 



The following commands give the user access to the cxccservcr functions, 
checkcxecs Kill off any exec whose standard input server or standard output server has died. 

dclcxec Delete an executive, specified by its exec id. The first exec created when die workstation is 

booted will always have an id of O. 

do Create an exec with a named file as its input This file should contain a list of V 

commands, cxacdy as you would type them, one to a line 

killprog Kill the program, if any, running in die specified executive. 

qucrycxcc Find out the status oi % the specified executive. Useful mainly for system testing. Sec 

QueryExec in the Program Environment manual. 

startcxec Create an exec in a new pad. The new exec will have the same context as die exec from 

which startcxec was invoked, NOT the [home] context For most purposes die view 
manager's Create Executive commands arc to be preferred over tliis one, as the view 
manager will not work on an executive created by startcxec. startexec prints out die exec 
id and prwess id of the new exec. 



V-SYSTKM 5.0 RIUWRKNCH MANUAL 



COMMANDS 



28 THE V DEBUGGER 



V-SYSTEM 5.0 REFERENCE MANUAL COMMANDS 



'IlIEV DEBUGGER 



29 



— 6 — 
The V Debugger 



6.1. Synopsis 

debug [-d] progName progArgl progArg2 ... 

6.2. Description 

6.2.1 . Invoking the Debugger With a Program 

Debug is an assembler-level symbolic debugger for s files created by die 68000 linker (ld68). It can be called 
as a command to the V exec and takes die following arguments: 

-d If the VGTS is available, then this argument causes an 10 pad to be created for the 

debugger which is separate from the one used by the program to be debugged. This option 
is a necessity for programs which read keyboard input via separate reader processes since 
these may interfere with die debugger's keyboard input requests. 

progName The name of the program to be debugged. 

progArg/? The nth argument of the program to be debugged. 

Thus, to debug a program which is normally invoked by: 

progName argl arg2 
one types 

debug progName argl arg2 
If a separate 10 pad is desired {for Vgfs resident environments only) then one would type 

debug -d progName argl arg2 

6.2.2. Postmortem Debugger 

The debugger can also be used as a "postmortem" debugger. The V execs (both die Vgts-bascd one and the 
non-Vgts-bascd one) have been structured so Uiat if an exception occurs in the program currently being run, 
the debugger is automatically loaded and given control. 

i 

6.2.3. Common Usage 

A program invoked with die debugger will start out at the debugger's command level. Breakpoints may be 
set and the program code and global variables may be examined. The program can dicn be started using die 
commands described below. 

A frequent "postmortem" use of the debugger is to obtain a stack trace to find out where a program 
incurred an exception and then quit. This is done by typing s after having been transferred into the 
postmortem debugger to get a stack trace, and q to quit: 
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I oroo aral arc-2 

Bus error on read from address f in process 2ed0024 

Instruction Program Counter Status Register 

1010 10172 10. 

B0> 10174 4880 main+2C extw dO 

stack trace 
-1 



6.3. Commands 

The debugger begins by displaying die line of code at which execution has paused, and then gives a period 
(7) as a prompt. The user can then enter commands using the keyboard. Most commands arc terminated 
with a carriage return; exceptions will be noted in the command descriptions. The only characters that may 
be used to erase previously typed input arc backspace (\b) and delete (Dl-L). 'Hie entire line may be erased 
by typing CTR1 .-u. When eliminating optional arguments in commands which take more than one argument, 
be sure to include the correct number of commas for die command. In this way die debugger can determine 
which argument is to be assumed. 

6.3.1. Definitions 

Within the command descriptions below, an expression is some combination of numeric constants, register 
symbols, globally visible symbols from die program being debugged, and the operators +, -, and |, 
representing 2's complement addition, subtraction, and bitwise inclusive or, respectively. Blanks arc not 
significant except in strings. All operations arc carried out using 32-bit arithmetic and evaluated strictly left to 
right 

Register symbols arc symbols which represent the various processor registers. The following symbols are 
rccogni/.cd: 

%d0 - %<17 Data registers - 7. 

%a0 - %a7 Address registers - 7. 

%fp Frame pointer (synonym for %u6). 

%sp Stack pointer (synonym for %a7). 

%pc Program counter. 

%sr Status register. 

In all commands except the rcplacc-rcgistcr (rr) command a register symbol represents die contents of the 
specified register. In the rcplacc-rcgistcr command it represents die address of die register specified. 

Globally visible program symbols arc names of program routines or global program variables. 

The single character 7 (dot) is treated as a symbol representing the last memory location examined. Its 
value upon entrance to Uk command level of die debugger is set Cb the current value of die program counter. 

6.3.2. Execution Control Commands 

expression, number, b 

Set breakpoint number (in the range 2- 15 decimal) at expression, expression must be a legal 
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expression, g 
expression, gb 

expression, x 

expression, y 
xx 



sp 



instruction address. If number \$ omitted the first unused breakpoint number is used. If 
expression is the named breakpoint is cleared, or if number is omitted then all breakpoints 
are cleared. If expression is omitted ail breakpoints are printed. Note: if expression is 
omitted then number must also be omitted or must be preceded by a comma in order 
distinguish it from being interpreted as the expression argument. 

Go. Start or resume execution at expression. If expression is omitted, then start execution 
at the current pc value. 

Go past breakpoint. Like go with no argument, except that if we are presently stopped at a 
breakpoint, dicn expression counts the number of times to pass this breakpoint before 
breaking. If expression is omitted, then 1 is assumed. 

Execute the next expression instructions, starting from the current pc and printing out all 
executed instructions. If expression is omitted, dicn I is assumed. Note: traps arc executed 
as single instructions: i.e. the instaictions executed in a trap routine arc not displayed or 
counted. 

Same as x except that subroutine calls arc executed as single instructions; i.e. do not 
descend into the called subroutine. 

xx is a synonym for y 

A synonym for x, except that each instruction executed is displayed on the same line as the 
command, providing a more compact display. No carriage return is needed to terminate 
this command; die semi-colon triggers execution. The typcout mode referred to in the 
command descriptions is described under the t command. 

Toggle the flag that determines whether the whole team stops at an exception or just die 
process that incurred die exception. The debugger's default behavior is to stop the whole 
team when an exception occurs, not allowing any of its processes to proceed until one of 
the above Execution Commands restarts die team. (Of course, at that point ANY of the 
processes could resume execution - i.e., single-stepping one process could allow another to 
execute indefinitely.) If this command is typed, an exception in any one process will not 
halt any of the other processes on die team. Typed again, die debugger goes back to its 
original behavior. 

Quit. Kxits die debugger and kills both the debugger and the program being debugged. 



6.3.3. Display Commands 

The following commands arc executed immediately without waiting for a carriage-return (CR) to be typed, 
and their output overwrites the current line. (This provides a more compact display format.) 



expression/ 
exprcssion\ 

/ 
\ 

<§ 

expression® 



Display die contents of expression. The typcout mode used is determined from the 
program symbol table and die current typcout mode. The value of dot is set to expression. 



Display the contents of dot after having respectively incremented (/) or decremented (\) it. 
The typcout mode used is determined from the program symbol tabic and die current 
typcout mode. 



Display the contents of the memory locations pointed to by the value of dot or expression, 



v-SYsrr-M 5.0 ri«:h-:rencf. manual 



COMMANDS 



32 THli V DHBUGGER 

respectively. The typcout mode used is determined from die program symbol table and 
the current typeout mode. The value of dot is set to the address of the memory location 
just displayed. Note that %pc will yield die contents of the memory location pointed to by 
the pc register (i.e. the current instruction) and that %pc@ will attempt to place an 
additional indirection on that memory location. %pc@ is almost always an invalid 
reference. 



expression^ Display the value of dot or expression, respectively. 

The following display commands are executed when a carriage-return is typed. 

d Display the contents of all the registers. 

s Print out a stack trace describing the chain of subroutine calls and their parameters. 

Warning: the debugger's stack trace examines the values of parameters as Uiey currently 
exist on the stack, not as they were when die routine was called. Routines which change 
the values of Uicir parameters will similarly affect the stack trace output 

expression, numiines. n 

Display die next' numiines memory locations, starting at expression. If expression is 
omitted, dion display starts at dot. If numiines is omitted, then 24 lines arc displayed. 

expression, numiines, p 

Display the previous numiines memory locations, starting at expression. If expression is 
omitted, then display starts at dot. If numiines is omitted, dien 24 lines arc displayed. 

type, t Temporarily set typcout mode to type where type is one of: 

V type out bytes as ascii characters. 

V type out bytes in current output radix. 

V type out words (2-bytcs) in current output radix. 

T type out longs (4-bytcs) in current output radix. 

Y, strLen&h type out strings. Set die maximum length of strings to bo slrl.englh. 

Hie maximum string length determines how far die debugger is willing 
to look for the end of a string, which is assumed to be a '\0' byte. Kor 
programming languages such as Pascal which don't terminate their 
strings with a '\(V byte diis limit is important to prevent endless string 
searches. 'ITic string maximum length is sticky (i.e. it need be set to the 
desired value only once). The default value is 80. 

T type out as symbolic assembler instructions. 

Note Uiat die type characters must be surrounded by single quotes. If no argument is 
supplied then die default typcout mode is used. This mode tries to set the typcout mode 
based on the type of symbol(s) being displayed and uses T format when die mode is not 
obvious. The new typcout mode stays in effect until execution is resumed with one of die 
Execution Control Commands. 

type, tt Permanently set typcout mode to type. The typcout mode is set to die default typcout 

mode if type is omitted. 

base, ir Set the input radix to base. If base is illegal (less than 2 or greater than 25, decimal) or 

omitted, dien hexadecimal is assumed. (This is the default radix.) 
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base, or Set the output radix to base. If base is illegal (less than 2 or greater than 25, decimal) or 

omitted, then hexadecimal is assumed. (This is the default radix.) 

offset, of Set the maximum offset from a symbol to offset. If offset is illegal (less than 1) or omitted, 

then hexadecimal 1000 is assumed. (This is the default offset) This command is useful 
when examining areas of the team, such as die stack, which are more accurately labeled by 
hex addresses dian by symbol + offset notation. 

charcount, si Set the maximum number of characters in a symbol which will be displayed to charvount. 
If charcount is illegal (less than 1 or greater than 128) or omitted, then 16 is assumed. 

6.3.4. Replacement and Search Commands 

expression I, expression!, type, r 

Replace the contents of the memory location specified by expression/ with expression!, 
expression! is interpreted to have type type. Note: It is not currently possible to replace 
strings with this command, and instructions should be specified! in 16-bit quantities and 
replaced with type T.. If expression! is omitted, then the value is used. 

register, expression, rr 

Replace die contents of the specified register with expression. If expression is omitted, then 
the value is used, expression is interpreted to be a 32-bit quantity. 

expression, lowlimit, high limit, type, f 

Search for (find) pattern in the range lowlimit (inclusive) to highiimit (exclusive). 
expression is interpreted as an object of type type. Objects arc assumed to be aligned on 
word (2-bytc) boundaries except for l-bytc types and strings, which are aligned on byte 
boundaries. A mask (set with the mask command) determines how much of the expression 
is significant in the search, unless expression is a string constant. The first three arguments 
to the search command arc sticky; thus if any of them are omitted then their previously 
specified value is used, f is the only debugger command which allows the specification of a 
string constant as expression. A string constant is delimited by the character " on cither 
side: to use " in die string itself, precede it with a Y An example of ii string is: "This is a 
string with \" in it". The typcout limit of strings determines how much of die string is 
significant in the search, not the search mask. 

expression, in Set the search mask to expression. If expression is omitted then is used. -l,m forces a 
complete match, I'm (that's hex checks only the low order 4 bits, 0,m will make the 
search pattern match anything. 

6.3.5. Help Commands 

h Print a brief description of each of the debugger's commands. 

w Print a set of internal debugger statistics. This was implemented for the convenience of the 

designers and may change frequently in content and format. It replaces the obsolete qq 
which, due to die debugger's unsophisticated command parsing will behave exactly as docs 

q. 

6.4. Bugs 

The debugger as it is currently implemented has some "features" one must be aware of. 

Currently, each instance of the debugger can debug only one team at a time. Programs that create and load 
new teams will cause problems because the debugger assumes, that it is always dealing with die same program 
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image. 

If a breakpoint is encountered anywhere between the receipt of a message and a later attempt to call 
RcrcadMcssageO on that message then the breakpoint exception will destroy the message value, yielding 
garbage in the subsequent call to RcreadMessagc(). 

The debugger assumes that any trace trap exceptions have been caused by its own single-stepping 
mechanism. Though it will recognize the first one, and print an error message, subsequent trap exceptions 
can cause intolerable behavior. 

The stackdump routines depend upon knowing the string names of the kernel routines to produce correct 
stack traces which include those routines. Right now, diis list is being kept up to date by hand. 

Putting breakpoints in code which is shared by two or more processes can be hazardous to your mental 
health. 
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— 7 — 
Ved: A Text Editor 



Vcd is the V system text editor. It runs entirely on a Sun workstation, using a session host only for file 
service. Its basic keyboard commands arc a subset of Kmacs. However, the mouse adds a whole new style of 
interaction with the editor. The multiple window capability of the VGTS is put to good use, as well. And the 
user will quickly notice that it responds much faster than Emacs on a normally .loaded system. 

Vcd manages one or more editing windows. Kach window is thought of as a viewport onto a buffer of text, a 
continuously accurate display of some portion of that text. A change to the buffer is followed immediately by 
a corresponding change to the display. In each butter there is a cursor, which is guaranteed always to be in 
the portion of the text displayed. Bach buffer normally has a filename associated with it, the file from which 
it was read or the file to which it was most recently written. 

7.1. Starting up 

Vcd runs under the V system executive, which is invoked as described in the previous chapter. Once inside 
the executive, type 

ved 

or 

ved filename 

The filename can be in any of the forms recognized by the V exec - a relative pathname, an absolute 
pathname, or [session host] followed by a pathname of either type. Vcd proceeds to read in the named file 
given, then requests a pad, its first editing window. This is indicated by the mouse pointer, which changes to 
the word "Pad". Move the mouse to the desired upper left corner of the pad and click any button. The pad 
will appear, and in it the first screenful of text will be displayed. The pad in which ved was invoked is 
reserved for displaying error messages and typing special text, such as filenames or search strings, which is not 
to be inserted into any butter. In normal use it is convenient to shrink this window down to a lew lines at the 
bottom. 

At the top of the editing window, there is a banner. When the banner is inverted, then this window is 
selected for input cither by the mouse or the keyboard. The banner specifics the vcd window number which 
is used by die window selection command (described in section 7.10) and the Vgt number (sec section 3.2). 
'Hie rightmost area is reserved for the file name associated with this window. If the file name has an asterisk 
(*) prefix, then vcd thinks that this butter has been modified since the last write or save of the specified file. 

As an added feature, there is a inverted line of text at the bottom of every vcd window. This is the fixed 
menu area of the window. It can be used to enter some frequently used commands using the mouse instead 
of die keyboard (a full description of the fixed menu is in section 7.6.2). 

7.2. Motion 

The following commands arc available to move trie cursor within a file: 
The four arrows Move thc.cursor in the direction indicated. 
tF, tB, backspace 
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Horizontal cursor motion. 

esc f, esc b, esc backspace 

Word-oriented cursor motion, csc-f goes forward to the end of a word; csc-b and esc- 
backspacc go back to the beginning of a word. 

tP, tN Vertical cursor motion -- scrolling if necessary. 

tA,tE Cursor to beginning, end of line. 

esc comma, esc period 

Cursor to top, cursor to bottom of visible region. 

esc <, esc > Cursor to beginning, end of text. 

tG Get out of special states. Whether you have just typed Escape or tX and didn't want to, or 

arc busy typing a search string, or whatever, tG will get you back to the normal state. 

tXtZ Quit the editor. If there arc any modified buffers, you will be asked if you want to save 

them. Here and in similar cases, if you arc warned and then decide you don't want to do 
die command at all, type tG to escape back to normal editing. 

tC Also quits, but first asks for confirmation, which should be answered with "y" or Return if 

you mean to quit. tC is kept for Unix compatibility, protected with a message because a 
multi-window edit can take some time to set up, and should not be at the risk of a single 
keystroke. In the future, tC is intended to serve a "quit local edit" function, when ved or 
something like it is a service available to programs like mail and send. 

7.3. Paging and Scrolling 

tV, esc v Page down, page up. 

tL Redraw die display. 

PR Scroll -- move the viewport down one line relative to the text 

PF2 Scroll backward - move the viewport up one line relative to the text 

tZ, esc z Synonyms for Pl v l, PR respectively. 

esc PF1 Moves die viewport 1/2 page down the text - half a tV. 

esc PF2 Moves the viewport 1/2 page up the text. 

esc downarrow, esc uparrow 

Synonyms for esc PF1, esc PH. 

7.4. Simple Editing 

Typing any printing character, or TAB, inserts the character typed. Other special characters arc handled as 
follows: 
tD Delete forward from the cursor -- the character under the cursor. 

DEL Delete backward from the cursor. 

esc d Delete word forward. 
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esc DEL, esc h 

Return 

tO 

tK 



tY 

escy 
Linefeed 

esc Tab 



tQ 



t\ 



Delete word backward. 

Inscn: a Linefeed, not a CR character - gets the desired effect 

Insert a Linefeed, leaving die cursor before it. 

As in Emacs. Delete the contents of one (logical) line, or the carriage return on an empty 
line, into the killbuffcr. A sequence of tK commands uninterrupted by any other 
command causes the whole section thus deleted to go into the killbuffcr. tK after any 
other command restarts die killbuffcr from scratch. 

Yank -- insert contents of die killbuffcr at die cursor. The killbuffcr is unchanged. The 
cursor ends up at the beginning of the insertion, and the Mark (see below) ends up at die 
end. 

Yank, but without disturbing the Mark. The cursor ends up at die end of the insertion. 

Insert a ncwlinc (Linefeed) and dien indent the new line to die indentation of the previous 
line, using tabs where possible. If the previous line is empty, it will look up until it finds a 
nonempty line and use that as the standard of indentation. 

Add indentation to this line equal to the indentation of the previous line. Intended use: if 
you type Return and wish you had typed Linefeed, this will make up the difference. 

Quote the following character. Allows you to insert non-printing characters (such as the 
useful tL, formfeed, which forces a page break on most printers) into die text. 

Quote the following character and insert it with the high bit set tQ and t\ arc the only 
exceptions to die tG command: dicy will quote a following tG, but that simply means die 
insertion of a character, which can easily be deleted. 



7.5. File Access 

Whenever ved writes a file, it preserves the previous version of that file (if there was one) by renaming it to 
its former name followed by ".BAK". 'ITuis myfilc.c becomes myfilc.c.liAK . 



tXtV 

tXtS 

tXtW 

tXtl 

esc ~ 
tXb 

tXc 



Visit a file, whose name will be requested. 'Hie hew file replaces the current one, so if the 
current buflcr is modified you will be asked before proceeding. 

Write the buffer back to die file from which it was read. 

Write the buffer to a file whose name will be requested. 

Insert file at the cursor. You will be asked for the file name. Cursor and Mark arc set just 
as in tY above. 

Forget that the buffer has been modified. 

Toggle the .HAK safety feature. Creation of .HAK files makes file writing take about 4 
times as long as it otherwise would, so if you really want diat speedup, diis will turn off die 
making of .BAK files. tX b again will turn it back on. 

Change current context. Th is command allows a user to change die way character string 
names arc interpreted. A context is similar to a directory in diat it defines which object is 
associated with a name. The file name represented in the banner of the pad should always 
be context independent. (Sec section 2.3.) 
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7.6= The Mouse 

The mouse offers an alternative way of doing several common editing functions, such as placing die cursor 
and deleting or moving text. The mouse has two functions: fixed menu selection and editing. 

7.6.1 . Editing With the Mouse 

Left button Click and release it at any character in the text: sets the cursor at that character. Click it at 

one character, move the mouse to another point in die window, and release: selects die 
text between the point of clicking and the point of release. While you arc moving the 
mouse with die left button held down, the region which would be selected if you released it 
at this moment is displayed in inverse video. When you release, your selection is defined 
and remains displayed in inverse video. Carriage returns arc invisible, so die selection of a 
carriage return is shown by black space from the end of the text on that line to die end of 
the window. Note that a selection and a normal cursor arc mutually exclusive. The 
importance of this will become apparent below. If you have a selection and click die left 
button, with or without moving, the former selection is deselected and a new cursor 
position or selection is chosen. 

Middle button When you have a selection, clicking die middle button deletes it into the killbuffcr. If you 
have no selection, nothing happens. The position of die mouse is irrelevant. 

Right button Brings back the contents of the killbuffcr and makes it selected. If there is nothing in the 
killbuffcr, nothing happens. If there was a selection already, its contents arc swapped with 
the contents of the killbuffcr. If there was no selection, the contents of die killbuffcr 
replace the cursor. 

7.6.2. Fixed Menu 

The fixed menu that appears at the bottom of every ved window provides the user with mouse oriented file 
perusal capabilities. Clicking the middle or right mouse buttons in the fixed menu area will execute die 
command diat is nearest the mouse cursor. All the commands in die menu could be entered from the 
keyboard, therefore they arc not described here. Refer to die sections on searching, scrolling, and regions for 
descriptions. 

In the fixed menu area, the semantics of the each of the buttons difTcr. The middle button (in general) 
means forward whereas the right button means backward. For instance, clicking die middle button at the 
hull-Page command will cause the window to be scrolled forward one full page and the right button will cause 
a reverse scroll. The commands Half-Page, Scroll-Line, and Search behave in diis same manner. The Tag 
command has exactly the same semantics for both buttons. Mark/Point is die only "different" command; in 
it, the middle button causes a jump to the Mark and the right button sets the mark at the point. Note that die 
left button has no effect on menu selection, to maintain continuity during dynamic selection. The Search and 
Tag commands will cither use die selected string as the pattern or prompt die user for one in the case of no 
selection. 

7.7. Searching and Replacing 

tS Search for string. Prompts for a string, and finds the first instance of that string after the 

cursor. Prints "Not found" if there is no such instance. If you type Return without typing 
any search string, the previous search string is used - tS Return is equivalent to PF3 as 
described below. Here and elsewhere, a ncwlinc can be inserted into the search string 
using the Linefeed key. It is echoed as an inverse-video backslash. Non-printing 
characters can be searched for, and arc echoed as like "tA". If the search succeeds, the 
string found is selected, and several special commands (described in The Right Hand and 
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die Left, below) arc available. In particular, typing s will repeat the search. 

tR Reverse search. Just like tS but searches backward. 

PF3 or esc s Repeat search. Forward search for the string most recently used in a tS or tR command. 

Works regardless of whether there is currently a selection or not. 

PF4 or esc r Repeat search backward. Like esc s but searches backward. 

esc q Query Replace. Prompts for a search string, then a replacement string. Then searches till it 

finds the search string, and selects that text Type y (yes) to replace, n (no) to leave it alone 
and go on. Other options arc described below. These special commands arc available 
whenever there is a selection, so Query Replace is easily re-enterable. Just use PF3 to find 
and select the next instance of the search string, and away you go. 

esc g Go to line. Prompts for a line number, and moves the cursor to the head of that line in the 

file. The first line is numbered I. If the number is too large, it will go to the end of text 
and notify you of the true line number there. 

7,8. The Right Hand and the Left 

When there is a selection, die cursor is not in a single spot, so it would not make much sense to insert 
characters at the cursor. So various printing characters arc used as special selection-mode commands. The 
most basic of these commands arc all assigned to left-hand keys. Thus one possible mode of operation is for 
the user to have his right hand on the mouse, selecting things, and his left hand at the usual place on the 
keyboard, giving commands which arc not available on the mouse buttons. Others of these commands arc 
designed for use with the search and replacement facility. 

Non-printing characters other dian those described below deselect, then perform their usual function as if 
the cursor had been at the beginning of the selection. 

space bar Deselect. The cursor lands at the beginning of die selection. All printing characters not 

mentioned here also have diis effect, but die space bar is recommended. 

Tab Deselect, but the cursor lands following the end of the selection. 

d Delete. Rxactly identical to die middle mouse button. 

c Rxchangc, Hxactly identical to die right mouse button. 

c Copy in place. A copy of die current selection is inserted right after it, and becomes the 

new selection. 

g Grab. The current selection is copied into the killbuffcr without deleting it 

s Search for the next instance of due selected string. This becomes the search string, as used 

in future Repeat Search or search-and-rcplacc commands. 

r Reverse version of s. 

PF3, PF4 Repeat search - they perform their usual function, using the stored search string rather 

than the current selection. 

PF1, PF2 Scroll - as usual, but unlike other commands they do not deselect unless the selection is 

being scrolled oft' the screen. 

tL Redisplay, with the selection near the top of die screen. Good for long selections which 

run off die bottom of the screen. 
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y Yes replace. Replace the selection with the stored replacement string. 

n No don't replace. Search for die next instance of the stored search string. 

backspace Undo replacement. Search backward for die first instance of the replacement string and 

replace it wid\ the search string. The resulting string is selected. 

Y Yes replace but don't move on. The selection is replaced and die result remains selected. 

u Undo in place. The current selection (which hopefully is the replacement string) is replaced 

with the search string. 

S Search for next instance of the replacement string. 

R Reverse version of S. 

q Start query replace. Takes the current selection as the search string, and prompts for a 

replacement string. Replaces the current selection, and goes on to the next instance of it, 
just as "y" would do. 

Q Set replacement string. The current selection is copied into the replacement string. This 

makes it possible to alter a Query Replace in mid-flight. 

7.9. Mark and Region 

Vcd maintains an invisible point in the buffer called Mark. Until otherwise set, it is at die beginning. It can 
be set by tXtM or Control-® (Control-spacebar is die same as Control-® on some keyboards). "Region" 
refers to all the text between Mark and the cursor. 'Hie following commands use these concepts: 

tX tM, t@ Set the Mark at Uic current cursor position. 

tX tX Exchange Mark and cursor (changing die display if necessary to keep die cursor on die 

screen). 

tX tK Kill Region. Region vanishes and becomes the killbuffcr -- so this command can be 

undone with f Y. Note that in Unix Kmacs this function is normally bound to tW. 

tX tR Write Region. Prompts for a file name, and writes the region into thai 111c. The buffer is 

unchanged. 

7.10. Windows and Buffers 

Vcd is normally started with one editing window, but it can support several. Fach editing window is 
associated with a separate editing buffer, which includes die text, cursor position, selection if any, associated 
filename, and whether Uiis buffer has been modified. Multiple windows on the same buffer are not 
supported. Since die correspondence is one to one, hereafter we refer to "window" meaning "window and its 
associated buffer". At any time one window is selected for editing, and is foremost on the screen. Window 
selection can be changed by clicking a mouse button in an unselcctcd window, or by pressing the appropriate 
number key on the keypad. Windows arc numbered, starting at I, in the order of dicir creation. 

The search and replacement strings and the killbuffcr arc universal across windows. Thus it is possible to 
kill some text in one window and yank it into another. It is likewise possible to search for a string In one 
window, then select another window and repeat-search on the same string. 

The window from which vcd was invoked is special. It cannot receive input except during certain 
commands, at which time it is selected automatically. It is never receptive to mouse input. 
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tX g Get file. Prompts for a file name, and reads it into a new window. If no file name is given, 

creates an empty window. Here and in all other cases, when a window is to be created the 
mouse cursor will change to "Pad" and let you indicate where the window is to go. If you 
abort the pad creation by pressing all three buttons, the command is aborted. 

tX d Delete the current window. Will warn you if it is modified. The next lower numbered 

window becomes selected. If the last window is deleted, ved quits, because it cannot live 
without a selected window. 

tX y Yank to window. The killbuffcr is copied into a new window. 

tX a Pull Apart Kills the Region in the current window and transfers it to a new window. 

tX m Merge windows. Asks the user to indicate a secondary window, and transfers its contents 

into the current window at the cursor position. The secondary window is then deleted. 
The secondary window is indicated by clicking the mouse in it 

tXl - tX9 Select the corresponding window. '. 

Mouse click in any unsclcctcd window 
Select it 

7.1 1 . Crash Recovery 

In an ideal world, this program would never crash. But in fact it sometimes docs - but it is so designed that 
it has to crash in two stages to lose your text Normally a crash only breaks the first stage, in which case you 
will get the message 

Editor crash! Shall I try to save this buffer? 

If you have any changes, and you value them, and the crash did not come during a save, it is probably a good 
idea to answer "y". A .BAK file will be made, so the danger of total loss is small. If this succeeds you will be 
asked 

Try to continue?. 

If you answer % y\ the inner editor will be recreated with the buffers just as they were. For some display- 
related errors, a tL at this point will set everything right However, you arc on shaky ground, and the best 
tiling to do first is save any modified buffers in other windows. 

If you are dumped into the debugger by an editor crash, the debugger command Suici de , g will destroy 
the process that got the exception. This will usually activate ved's crash recovery facility, as described above. 

Ved tries to detect the cases in which it runs out of memory. In some activities, such as reading in a file, it 
will simply refuse. In others, such as a kill or an insertion, you will get the message 

Out of memory I Please do one of the following: 
Pick a window to delete 
c'- continue (after you free something) 
q - save and quit 
tC - quit without saving 

Ved cannot proceed without more memory, and cannot exit gracefully from Uiis activity, so you have to help 
it out To pick a window, select it with one mouse click and signal it with a second click. It will be saved if 
modified, then deleted to reclaim its storage. If you have anything else going on on your Sun, you can delete 
a view or terminate a program or delete an exec to free some storage. After doing so, type c to continue. If 
this won't work, type q to try to save everything and quit gracefully. It will save the current buffer last trying 
to avoid die dangers of saving a half-modified text tC is a last resort a quick and dirty quit 
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7.12. Hints on Usage 

Ved has no repeat factor like the tU of Emacs. Use the hold-repeat feature of the arrow keys to move the 
cursor around - they happen fast enough that this is rather workable. Take advantage of die scrolling 
features -- you will quickly become addicted to the convenience of getting your material centered on die 
screen exactly as you want it. When making scattered changes, you will find the mouse very helpful. 
Arrow-repeat will get you there fast, but a mouse click wilt get you dicre now. Likewise sclcct-and-dcletc is 
the fastest way to delete a small piece of text so you can type something to replace it. 

Ved is almost too large now to run on a 256 K workstation. Use it only with one or two page files on such 
workstations. Attempts have been made to catch the event that ved runs out of memory, and give you a 
chance to save, but this is not reliable. . 

If you get into a weird state, try tL, it often restores sanity. If that fails, a save may work anyway - it uses 
only the textual data structures, and it is the display, structures that usually foul up. 

Ksc followed by a number key invokes one of the debugging routines. Avoid them. 
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— 8 — 
Draw: A DrawingEditor 



The Draw program is meant to fill a specific void in the V-System software. Specifically, the lack of an 
analog for the Alto Draw program is addressed. The V Draw program is not identical to its Alto counterpart, 
although as much symmetry as possible was included. If you have any questions about the behavior of the 
program, try using the Help command. It will (hopefully) provide some meaningful information. 

This program runs under the vgtscxec only. Since it uses splines, it will not run under the small version of 
the VGTS configured for 256k Sun workstations. 

8.1. Conceptual Model 

ITic conceptual model behind this program is one similar to a person drawing regular objects on pieces of 
paper. The drawing pen has a number of different nibs (tips) which can be selected. Similarly, .the "ink" and 
fill pattern used to shade areas also comes in several flavors. The ink can be cither transparent or opaque. 
If transparent ink is used to fill an object, anything under the object will show through. If opaque ink is used, 
underlying objects will be obscured. The Bring to Front (raise) and Push to Back (lower) commands are 
useful for shuffling which objects lie on top of each other. Kach object lies entirely in its own plane, so it is 
impossible to create works similar to those popularized by M. Eschcr. 

Curves arc generated using B-Splines of various orders. By default, all curves arc of order 3, and thus use 
quadratic interpolation. The Alter command can be used to change die order of the interpolating splines. 
Automatic filling (shading) of closed objects (specifically,, closed curves, closed polygons, and certain 
templates) is possible. . . " 

A GROUP is a collection of cxistings objects lumped together and treated as a single unit. Groups arc useful 
for replicating completed symbols and figures in several places. 

A variety of standard shapes are provided, and arc referred to as templates. Templates for Arrowheads 
(open and closed, wide and narrow) exist, as well as templates for rectangles, circles, and ovals. I ; .ach object 
on the screen has a type, so while it is quite possible to create a rectangular closed polygon which appears 
identical to a rectangular template, they arc of distinct type. This is important to bear in mind because 
whenever you arc asked to select an object on the screen, die program will only examine objects of a certain 
type, and so some confusion might arise when die program doesn't find die diing you arc right on top of. 

8.2. Screen Layout 

When die program is first invoked, it will create two new windows on the screen. The large empty one is 
die main drawing area (known as "drawing area" to die Vgtscxec), and die smaller one is the commands 
window (known as "draw menu" to the Vgtscxec). The drawing area is zoomablc (for instructions on how to 
use the Vgtscxec, sec die V Commands Manual), and die grid spacing available at normal magnification is the 
same as that used by die program. Since the program has no way of knowing what magnification you are 
using, it aligns to the unzoomed grid values. The VGTS will place grid points at a constant separation, 
regardless of magnification. You may create additional views, move existing views, etc., to your satisfaction. 
The default drawing area is in die proportion of 8.5 by 11, and centered. A frame is put around the actual size 
of a drawing page to provide some reference points if you zoom die view or change its centering. The frame is 
normally not visible, as it lies entirely outside the default view. It will not appear in any output. 
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The Menu window is divided into three separate menus. One consists of action commands (Rotate, Scale, 
Move, Copy, Draw, Alter, Erase, Push to Back, and Bring to Front), which place the program into a state 
where it is waiting for you to specify certain actions. Typically, you will need to specify an object type (ALL 
OBJECTS, TEXT, OPEN CURVE, CLOSED CURVE, CURRENT OBJECT, OPEN POLYGON, CLOSED POLYGON, GROUP, 
or template) and then some data points. A second scries of menu options runs along the bottom of die 
menu window. These arc the commands which control various defaults within the program. For example, if 
you wish to change the default font which new text is displayed in, select the Text default option in the lower 
left corner of the menu (not the object type text under the "Objects" column), and make the desired 
selection in the popup menus which will appear. The third section of the Menu is the list of permanent menu 
selections (Ex1 1, Hel p, Mi sc, Undo, Abort, and Done). These commands are valid most of the time. In 
particular, you can always hit He 1 p. 

The original window which you used to run the draw program will serve as a combination history log and 
prompt file; The program will print many prompts in this window, telling you what it expects you to do next, 
and what it didn't understand of your last action. When you ask for Help, it will appear in this window. 

8.3. Command Input 

The program accepts all command input through the mouse. Clicking the mouse near a command in the 
Menu is sufficient to indicate to the program that you wish to specify that command. Clicking the mouse in 
the drawing area will cither specify a data point or a command, depending on which mouse buttons arc used. 
More on that later. Sometimes input is required from the keyboard. Due to limitations of the VGTS, when 
the program is requesting input from the keyboard, clicking the mouse will have no immediate effect. Once 
the program gets around to asking for mouse clicks again, all of the saved clicks will be processed. 

Occasionally the VGTS will have difficulties synchronizing communications. This almost invariably occurs 
when you hit a character on the keyboard while the program is expecting a mouse click. When this happens, 
a message similar to 

Sync error - Bxpcctcd 037, got 040 
will appear. After this happens, things usually get a little strange. The program will starting complaining 
about 

Internal Rrror: Bad mouse buttons 170 at (5, 89) 
(maybe with other numbers) or more commonly 

Missed! Please select a menu command. 

and refuse to recognize anything you do as intelligible. Do Not Despair!! The remedy for this is to 
deliberately force more sync errors (by alternately typing a character on the keyboard and attempting 
innocuous commands with the mouse, like I Iclp) until a full cycle has been completed. This typically requires 
you to force three more synchronization errors, and then everything will be completely functional again. 

8.4. Control Points and Sticky Points 

When you create a curve, you will be asked to specify the Control Points of the spline. These points arc the 
places which you wish the curve to pass near. Hie more control points you put in one place, the nearer the 
curve will come to that place. Also, placing multiple control points at a single point will make the curve much 
"sharper" at that point. Except for the end points of open curves, and multiple control points, the curve will 
not pass through any of the control points. 

Sticky points (similar to Knots) arc points which actually lie on the curve. They arc calculated by the 
program to help you with the alignment of objects. There will be the same number of control points and 
sticky points on curves. Polygons arc a special case, in that since the control points of a polygon actually lie on 
the "curve", the program considers them to be sticky points too. This means that the sticky points on 
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polygons tic at the corners and in the middle of each edge. Sticky points for bounding boxes (e.g., for TEXT 
objects) arc the same as those for polygons. 

8.5. Mouse Buttons 

When the mouse is clicked inside the Menu, it is unimportant which mouse buttons you use. Within a 
popup menu (a list of choice which "pops up" after you do something), you can abort by cither clicking 
outside the menu or by pressing all three mouse buttons down and releasing them. In general, you don't have 
to release (or press) the buttons all at once, but the mouse position is based upon where the cursor is when 
you release the last button. 

Clicking the mouse inside the drawing area can cause one of several different commands (and mouse 
locations) to be used by the program. The use of mouse keys within the drawing area is as follows: 

Buttons Effect 

X - - Specifies a data point right where you are pointing. 

- X .- Requests the program to find a sticky point. 

- - X Requests the program to use the nearest grid point. 
X X - The Almost Done command, (see below) 

X - X Requests that a Checkpoint be made. 

- X X Equivalent to the "UNDO" command. 
XXX Equivalent to the "ABORT" command. 

Sticky points arc points located on or near existing objects on the screen. 'ITicy arc useful for connecting 
lines to objects, specifying points actually on the object, etc. groups themselves do not have sticky points, 
although the objects within a group may. Curves have one sticky point per control point. These points arc 
located midway between each pair of control points. When you request that the program select a sticky point, 
it will choose the nearest such point which is within a given radius (about I inch). If you arc further trying to 
specify a point on a specific type of object, the search for a suitable point is begun again from die previous 
result Naturally, if the original mouse click relocated to a sticky point on an object of die proper type, that 
will be the closest point for any further searches. 

Grid points arc spaced every 16 pixels (at normal magnification). If you wish to sec these grid points, use 
the Toggle Grid command within die Vgtscxcc. l ; or printed output, pixels arc assumed to be distributed at 
100 per inch. 

The Almost Done command is quite similar to Uic Done command described below, in that it tells the 
program you arc satisfied with the selections you have made, and that you wish the program to accept them. 
Unlike the Done command, it docs not tell the program that you arc completely finished with whatever you 
were doing. Instead, it permits you to, for example, erase several objects of die same type without having to 
go to the Menu each time and specify the Erase command and die object type. 

It differs from a "repeat" command in that it docs not force the program to create a checkpoint before 
beginning Uic next command. As a special case, when in conjunction with the Draw command, Almost Done 
and Abort behave slightly differently. Abort will cause Uic last item you drew to be removed, and Undo will 
subsequently remove all.of Uic others. Normally. Abort would cause ail changes since the command began to 
be removed. 

This command is also quite useful when drawing a scries of objects of similar type. You can specify that 
you wish to draw a closed curve, place die control points for die curve, and Uicn confirm with die right two 
mouse keys (Almost Done). The program will complete die curve you have outlined, and wait for you to 
specify another closed curve, just as if you had confirmed with Done, and then selected Draw Closed 
Curve again. 
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8.6. Selecting Objects 

The standard-method of selecting an object is to first choose the object type and then to point at the desired 
object on die screen, using some combination of mouse buttons which specify a data point. If you select the 
wrong object type, simply point at and choose a different object type before you select the object itself. As a 
short cut, the program maintains a notion of what it considers to be the "Current Object". This will be the 
last object you selected. If you choose the object type CURRi-NT owner, and it is unambiguous as to what the 
current object is, this will suffice. After you select an object, diat object will be "highlighted" on die screen. 
This normally consists of frame or bounding box appearing around the object. If the program misinterprets 
your pointing, use the Undo command (also available by pressing the right two buttons on the mouse) and 
then point to a different location on the screen. 

The most notable exception to this process is die mcdiod for selecting groups. Since individual objects can 
appear in several groups, a popup menu appears when you select the GROUP object type, listing all of die 
existing groups. Either choose one of these groups from the menu, or click outside the menu to abort 



8.7. Action Commands 

There arc nine action commands. Fach is useful for manipulating one or more objects. Typically, each 
action command will require die selection of an object type. 



Rotate 



Scale 



Move 



Copy 



Draw 



Alter 



Erase 



This command will permit you to select an object, specify a fixed point about which die 
rotation is to take place, and two points which will define die angle of rotation. 

Text is rotated about its positioning point. Only the position of the text is changed - the 
orientation of individual letters is constant 

This command will permit you to select an object specify a fixed point for the scaling, and 
two points which define the scaling vector. This command is useful for expanding and 
contracting objects. l 

Scaling text will not change its size or font It will change the location of die string based 
upon its positioning point 

'Hiis command will permit you to select an object and then specify a pair of points which 
define a displacement vector. This vector tells die program how far and in which direction 
to move die object. By using diis command, you can move existing object about on the 
screen. 

This command is similar to Move, except diat it leaves behind an image of die object. If 
you copy anything odicr than a group, the two resulting items arc completely independent 
Changing one will not affect the other. Groups, on the other hand, work differently. 
When you copy a group, it simply creates a new image of die same group, appending ", 
copy n" to the old group name, where n is a small number. 

This command lets you create new objects. Since it is anticipated that most of the time 
spent in diis program will be drawing new objects, this is (so to speak) the default 
command. If you ever select an object type without giving a command first die program 
will assume that you implicitly meant to draw an object of that type. 

This command is useful for changing die characteristics of an existing object. It will permit 
you to move the control points on splines, change die filling and nib selections used to 
draw objects, etc. Currently UnimplementetL 

This command allows you to delete (erase) objects from the screen. If you decide you just 
don't want to sec an object any more, erase it. If you decide that the last command you did 
was a mistake, you probably want to use the Undo command. 
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Push to Back Also known as Lower, this command will place die selected object behind all of the other 
objects. This is useful when you use opaque ink to fill something, and it winds up 
obscuring an object you want to see. 

Bring to Front Also known as Raise, this command functions much like the one above, except that it will 
place the selected object on top of all of the other objects. Note that you can still point to 
objects you can't see -- the program will find sticky points on completely obscured objects 
with no difficulty. 

8-8. Object Types 

There are nine selections widiin the Object type menu. Some of the selections arc obvious, some are not. 
All are meaningful for selecting existing objects, but the "Draw All Objects" command is not. 

All Objects This will permit you to select all objects at once. If you decide, for example, to move 

everything on the page a bit to the left, then this is the object type you want. The CI ear 
Screen command (available under M1sc) simply docs an "Erase Al 1 Objects", and 
then sets the dirty flag to false. 

Text As is obvious, this will select any text string. It doesn't matter what font the text is in -- it is 

all of object type text 

Open Curve An open curve is a spline with open end conditions. When you create one, die first and last 

control point you specify will actually be on -the curve, and die curve will be tangent to its 
convex null at these points. (It gets straight at the ends.) 

Closed Curve Closed curves arc splines with closed end conditions. To create one, you specify all of the 
control points you desire (the program will build a frame for the spline to help you 
visualize the resultant curve. You do not need to try to get die first and last control points 
in the same place - die program will close objects automatically. Closed curves can be 
filled. 

Current Object This will select the current object, if one exists. Ff you attempt to "Create Current 
Object'Ythc program will interpret this as a request to create an object of the same type 
as die current object 

Open Polygon A bunch of connected straight lines. (Internally, dicsc arc just splines of order 2, duis using 
linear interpolation.) 

Closed Polygon Also straightforward. Closed polygons can be filled. The program will automatically add 
the last edge, closing the polygon. 

Group Groups arc a bit tricky. A group consists of several existing objects, lumped together and 

treated as a singled named object To create a group, you select as many existing items as 
you like, and they arc all placed into the group. Once items arc inside a group you cannot 
select them by normal means. 'lTicy are in effect hidden inside the group. 

Groups arc useful if you have a complicated, complete figure which you wish to deal with 
as a whole. Due to internal limitation, you can't have more dian some fixed number of 
groups active at one time. 

Template Templates arc standard shapes. The broad classes of standard shapes arc arrowheads, 

circles, ovals, and rectangles. Arrowheads can cidicr be open or closed. Closed 
arrowheads arc filled with black ink. 'Hie nib used to draw an arrowhead will be die same 
size as the die current nib, but will be circular. "- : 

Rectangles and Ovals arc both created by specifying two points on a long diagonal of the 
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bounding box. You can give either the upper left and the lower right or the lower left and 
the upper right. 'Hie program doesn't know the difference. 

Circles arc created by specifying the center of the circle and a point on the circle. Since 
circles arc actually high order splines (5 th order, using quartic interpolation), they arc not 
truly circular. If you draw a really large circle, it is possible that the point you specify for 
being on the circle will be off by as much as a quarter of an inch or so. For normal sized 
circles, there will be no difficulties. 

8.9. Default-setting Commands 

There arc a number of Menu selections which control various defaults within the program. They can be 
selected at any time. They are: 

Text When you select this command, a popup menu will appear. You can use this menu to 

specify cither the method of positioning text, or the general class of font you wish to use. 

There arc three different ways of positioning text - you can specify (with a data point 
entered via the mouse) cither the bottom left-hand corner of die bounding box for the text, 
the center of the bottom edge of the bounding box for the text, or the bottom right-hand 
corner of the bounding box. Initially, the program positions text based upon the center of 
the bottom edge of the text. You can only specify a point on the lower edge of the text 
- the program will automatically compute where the bounding box for the particular piece 
of text lies. If you arc confused about where text should appear, try positioning a few 
strings, using the exact positioning (leftmost) mouse button. 

If you wish to change the font in which new text is displayed, choose one of the font menu 
selections. A second popup menu will appear, listing all of the available fonts. The 
"Standard Konts" category contains die fonts which can be considered to be mundane text 
fonts -- variations on Helvetica, Times Roman, and a few randoms like Clarity 12 and 
Cream 12. The "Unusual Fonts" selection contains everything else - Old Knglish 18, 
Hebrew, Cyrillic, Greek, API,, Math, CMR, etc. There arc some fonts, like Gates 32 and 
Template 64, which arc very difficult to use unless you arc quite familiar with diem. They 
arc included primarily for completeness sake. 

Kill on/off 'ITiis toggle controls whether or not closed objects (Closed Arrowheads, Rectangles, Circles, 

Ovals, Closed Curves, and Closed Polygons) arc filled by default. If you wish to use 
created filled objects, set Uiis switch to Kill on. Toggle die switch by pointing at it and 
clicking the mouse. 

Nib If you wish to change the nib (paint brush?) used to draw lines, select diis command. 

There arc four nibs, each of which comes in four sizes. The program initially uses a 
Circular nib of size 1. The four nib shapes arc Square, Circular, a horizontal Dash, and a 
vertical liar. The four sizes arc (unsurprisingly) 0, 1, 2, and 3. Size is a single pixel, so all 
of the nibs look die same at that size. An example of the current nib, at die current size, is 
displayed in diis area. 

Fill This command allows you to change the fill pattern used to shade closed objects. A small 

square section of the current 111! pattern appears in diis area. When you select Fill, a popup 
menu will appear, permitting you to cidier toggle the use of opaque vs. translucent ink or 
select a general class of fill pattern. 

The "Striping Patterns" consist mostly of lines drawn at various angles. The program 
initially uses the one pattern least like straight lines but still considered, a striping pattern: 
Chain Link.- 
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The "Gray Tones/ Area Patterns" selection consists more of patterns which arc cither 
various shades of gray, or arc regular and (to some) uninteresting. These patterns are 
useful for highlighting objects. 

The 'Textured Patterns" arc supposed to be more representative of actual textures. The 
names for these patterns are supposed to be suggestive of their appearance, but many of 
the names arc nonetheless obscure. 

8.10. Permanent Menu Commands 

There are a few commands which are generally useful, and arc thus considered permanent Not all are 
meaningful at all times, but arc still useful enough to be given an entry on the Menu. 

Exit This command will exit the program. It can be used at any time. If you have performed 

any command since cither clearing the screen or writing a file, the program will ask you to 
confirm that you actually wish to exit even though there arc unsaved changes. Typing "y" 
will confirm. Typing anything else will abort the command. Note that since the program 
is reading input from the keyboard when asking you to confirm, any mouse clicks you 
make will simply be queued, and when you do type at the keyboard they will all be dealt 
with. In particular, be careful about using the Abort command here. 

Help This command will provide a brief description of any other command you like. To get 

help on a specific command, just select that command after you select help. To get help 
with the mouse buttons, push any one button in the drawing area. To exit help, select Help 
again. You can ask for help at any time. 

Misc This command is actually a front for a collection of less frequently used commands. The 

various commands arc for clearing the screen (only valid if no other command is in 
progress), reading and writing files, generating press files, and toggling debug printouts. 
The debug printouts arc long and plentiful -- they arc also meaningless to the uninitiated. 

Reading a SUN draw file docs not clear the screen - it adds the new objects to the current 
display. Press files currently unimplementetL 

Undo There arc actually two forms of the Undo command. If you select it while at the top level 

(when there arc no other commands in progress), the effect will be to revert to the previous 
checkpoint, in effect undoing the last command. The program maintains a list of 10 
checkpoints, so you can undo up to 10 commands. 

Checkpoints arc copies of the complete suite of the drawing area. The program will make 
one before it starts any action command. In this way, the Abort command doesn't need to 
keep track of incremental changes during the processing of a command. 

If you give the undo command while in the process of specifying another command, it will 
attempt to undo your last choice. If you arc specifying data points. Undo will delete the 
last point you entered. If you are selecting an object. Undo will unselect the object and 
permit you to choose again. 

Abort This command will abort any command in progress. In general. Abort will also revert to 

the last checkpoint, since action commands all make a checkpoint before they begin 
processing. 

Done This command is used to tell the program that you arc happy with all of your choices, and 

arc done specifying parameters. After you hit Done, the program will attempt to perform 
whatever command you arc executing, and will display the results. Note mat by pressing 
down the left two mouse buttons while in the drawing area, you can give the Almost 
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Done command, which will confirm all of you selections, but not stop the command. In 
this way youcan, for example, create several objects at once. Note, however, that if you 
use the Almost Done command, you arc not guaranteed that a checkpoint will be made. 
If you create several objects with Almost Done, and then hit Abort, some (perhaps even 
all) of the new objects may be aborted also. 
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bits: a bitmap and font editor 



b1 ts is a special-purpose editor for working with bitmaps and fonts. It makes intensive use of the VGTS. 
The VGT of the executive under which bits is started up, is used to display various status information, as 
well as being the menu of commands to execute. When started, bits will ask for you to create a new view in 
which the actual editing is performed. If you request to view sample text, you will be asked to create a third 
VGT (see below). These last two VGTs can be zoomed. 

9.1. Command Input 

In this chapter, when you arc asked to do the command [xxx], it means that you should select and click 
the mouse at the field [xxx] of the status/command VGT. You get the same feedback as with pop-up 
menus, with the field in inverse video. Some of these fields, when activated, expect you to type in some 
number or string. In those cases, you have the full power of the line editor, until you type a <rcturn>. (To 
abort input, type CTRL-g.). 

9.2. Rasters 

The important thing to remember is that bits handles pointers to bitmaps. These we call rasters. A raster 
also contains size and offset data, so it can point to part of a bitmap. You can name a raster using the [Store 
with new name] command, and later retrieve it from the Table of saved rasters. You can thus 
save multiple pointers to the same bitmaps under different names. If you change bits in one of the bitmaps, 
the bits will also change in the other rasters, since they refer to the same bitmaps. Use die [Save a fresh 
copy] command to make a virgin copy of a bitmap, which is guaranteed to have no other rasters pointing at 
it. 

9.3. Changing Raster Size 

To change the size of a raster, point at die boundary, click the middle button and "move" the boundary to 
where you want it. You can also change die size of a raster with die [Width] and [Height] commands. To 
do this, select one of dicsc fields, and type in a number. The absolute value typed in becomes the new size. If 
the value is positive, the old and new rasters coincide at die top left corner; if die value is negative, they 
coincide at the bottom right corner. 

Note that when you change a raster's size, all other rasters pointing at the same bitmap will be adjusted to 
point at whatever bits they used to point at. ITiis is true even when you increase die size. (When the size is 
increased, and the underlying bitmap is larger ihun the part pointed to by the current raster, die hidden part 
of the bitmap will appear. 1 f tiiis isn't enough, a new biunap will be allocated, and all the pointers adjusted.) 

9.4. Bitmap I/O 

You can read and write bitmaps in .sun format (as used by die photo program), using die [Read 
paster] and [Write raster] commands. To write a raw raster in hex suitable for putting in a C 
program, use die [Write hex] command. 
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9.5. Painting 

To set (blacken) a pixel, point at it with the mouse, and click the left button. To clear (whiten) a pixel in a 
bitmap, use the middle button. 

9.6. Inverting a Raster 

Selecting [Invert black and white] inverts the interpretation of black and white pixels. This 
interpretation is actually stored as part of the raster object, so no pixels are actually changed (except on the 
display). 

9.7. Raster Operations (BitBIt) 

You can do a general 2-opcrand BitBIt with the [Raster operation] command. The current 
(displayed) raster is used as one of the operands (the "destination"), so this should be selected first. Then give 
the [Raster operation] command, after which you will be asked to select an operation. Available are 
plain copy, 'and', 'or' (paint) and 'xor'. In addition, the [Invert Source] modifier first inverts the source. 
[Invert Destination] docs die same for die destination, which means inverting the destination 
operand andtiv: output result Finally, you must select the other operand (the "source") from the name table. 

You can also select [Get the empty raster] as a source. This gives you an infinite plane of white 
pixels. This, together with the [Invert Source] option, allows you to conveniently clear or set any 
rectangle. 

9.8. Reflection and Rotation 

Selecting [Reflect/Rotate] will do one of these transformations. (A popup menu asks for the 
particular transformation.) Note that the result is a "fresh" raster: There arc no other rasters or tables 
pointing at its bitmap. 

9.9. [Replace in table] 

This command asks you to select an clement in the raster table or the current font. The clement is replaced 
by the current raster. If a [Table of saved raster] dementis replaced by the I -impty Raster, its space 
is freed. 

9.1 0. Making a Copy of the Screen 

You can make copy of the frame buffer, with a little bother. Select [Get f ramebuf f er], which gets a 
pointer to the frame-buffer. You should now use [Height] and [Width] to reduce the time and space 
required to deal with it. (The framcbulTcr is big,) You should [Save a fresh copy] to sec what's going 
on, and then use the middle button to select the part that interests you. This will be slow, since such a big 
raster is involved, and you will also have to use the Vgts window manager commands. 

9.11. Fonts 

A font is a collection of characters. From bits' perspective, a character is a bitmap with some extra 
information, bits currently knows about fonts in the following formats: 

• sf format ("Sun format"), which is specially optimized for the Sun graphics hardware. (The name 
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should probably be changed, since it conflicts with Xerox' Spline Format.) 

• The same format, but the font is stored in an archive (library) of relocatable binary files. Thus fonts can 
be linked in with programs, or read in at run time. The standard fonts are stored in 
/usr/sun/"Mb/1ibsfsonts.a. 

• Pxl format, which can be generated by MctaFont, and is used by a lot of the TeX people. 

To read / write a font, select the desired field in the Read font j Write font table. Note that you 
cannot write a font to an archive. 

9.11.1. Displaying Fonts 

When a character in a font is displayed, there arc funny lines sticking out of the bitmap picture. The two 
horizontal lines show where the baseline of the character is. The lower vertical line shows the starting position 
("origin") of the character. The top line indicates die width of the character, and shows where the next 
characters should start. You can select any of these lines (with the middle button), and adjust them with the 
mouse. 

9.1 1 .2. Font parameters 

This is a section of die pad with magic numbers about the current font. They can all be changed, but you 
should know what you arc doing. 

Design size is the size in points at which the font is designed for. Magnification is one thousand 
times die number of times the image is magificd, relative to a default Pxl resolution of 200 pixels/inch. To be 
compatible with the Altos, we have decided that the resolution of the Sun display should be defined to be 80 
pixels/inch. This means that the 1.0 magnification will have the magnification parameter of 400, which is 
somewhat small. Both these are TcX/Pxl parameters. 

[Raster al ignment] is the bit boundary character bitmaps should be aligned on in sf font files. It 
must be 1, 8, of 16. 

9.12. Sample Texts 

To study how a text string would look at no magnification, select [Sample text]. You should then type 
in the text you want displayed. This text will be placed in a new VGT. To change the lext, just rcsclcct 
[Sample text], the old text will be placed in die line editor buffer, to simplify small changes. If you edit 
the font, select [Redraw] to update die sample. 

Note diat in the sample, die character • \ • is special. It is used to indicate special non-ascii characters, as in 
C. Specifically, ' \ ' followed by a 3-digit octal number is die character with diat ordinal value. \\ displays \, 
and \b, \t, \e, \r and \n are Backspace, Horizontal Tab, 1'^scapc, Carridgc Rcturcn and Line Feed, 
respectively. \Q, \A, ... \_ arc control characters: tQ, tA, ... t_. 

9-13. Printing a Raster 

There is a Unix program to convert a . sun file to a .press file. To run it (on some Stanford VAXcn), do: 
/usr/sun/src/graph1cs/p1x/sunpress -p X. press X.sun 

This, together with the [Get f ramebuf f er] command, allows you to print a hardcopy of the screen .on a 
Dover printer. 
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9.14. Bugs and Problems 

.sun files use 1 to mean 'white' while bits uses 0. This means that you should [Invert bl ack and 
white] after reading and before writing, if you want to use the bitmaps for programs like sunpress and 
photo. 

The are some limitations on how bitmaps arc displayed by the VGTS. A bitmap can only be should 
magnified I, 2, 4, 8, or 16 times, so other zoom factors will be wrong. Also, it is over-conservative when 
clipping rasters, which means that a whole row of bits could be missing. 

Raster operations do not take into account that rasters may be overlapping. 

bits is not very robust against tilings like running out of memory. Caution would imply diat you save 
your work often. 



V-SYSTF.M 5.0 RliW'.RI«NCF. MANUAL COMMANDS 



AMAZE 55 



— 10 — 
Amaze 



Amaze is a game for two to five players which runs under the plain (non-VGTS) exec (VV). If you sec the 
letters VGTS in a small window on your screen you are not running the plain exec, See section 2.2 for 
instructions on how to start up the plain exec. 

To run amaze, type the command 
amaze 

If no one else is playing, it will type "New game starting" and then draw the maze. Otherwise it responds 
with "Joining game as player number x" and then draws the maze. Your player token, called a monster, will 
be sitting in the center of the screen just above a checkered flashing door. From this point, you control your 
monster through the keyboard. The commands arc: 

i Move the monster up. 

Move the monster down, 
j Move the monster left. 
1 Move the monster right, 
k Hold the monster at its current position, 
a Let the monster's moves be selected randomly. 

e Fire the monster's missile up. 

c Fire the monster's missile down, 

s Fire the monster's missile left, 

f Fire the monster's missile right. 

(Note: the missile can be fired only once every six 
seconds.) 

h Hide the monster from other players — no shooting allowed 

while hidden, 
v Let the monster be seen again — can shoot again, too. 
(Note: monsters stay hidden for ten seconds, but once 

they become visible, they remain visible for 16 seconds.) 

Set monster velocity to 0. 

1 Set monster, velocity to 1. 

2 Set monster velocity to 2. 

3 Set monster velocity to 3 — the starting velocity. 

4 Set monster velocity to 4. 

5 Set monster velocity to 5. 

q Quit the game, but continue to watch other players. 
t Rejoin the game just above the door, 
r Rejoin the game at a random corner in the maze. 
Ctrl-C Terminate your involvement with the game. 

Note that to leave the game entirely you hold down the CTRL key and type *c\ 
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To rejoin the game after being shot by another monster, use either the t or the r command. The game 
currently docs not keep score of the number of hits you inflict or surfer. 

Problems and questions should be directed to Eric Bcrglund -- bcrglund@Diablo. 

checkers allows you to play a game of checkers against the computer. This version of the program executes 
entirely on the player's workstation. 

On starting the program, the view manager will prompt you for the position of the VGT representing the 
checkerboard. 

The player moves the 'red' (white) pieces: the program's pieces arc black. You arc expected to make the 
first move. You can, however, force the program to move first by "passing". (Sec the paragraph describing die 
menu, to follow.) To make a move, move the mouse to the square containing the piece that you wish to move, 
and click cither the left or the middle mouse button. If this piece can be legally moved, it will then be 
highlighted. Complete the move by moving die mouse to the destination square and once again clicking the 
left or the middle button. 

If the move that you have selected is legal, your piece will be moved, and the program will then make its 
move. Note dint having selected a piece to move, you can abort this selection by clicking an illegal destination 
square (the source square itself, for example), if a capture of an opposing (ic. black) piece is possible, your 
next move must be a capture. A message indicating such "forced captures" will be displayed just below die 
board. In such a case, the program will not allow you to make a move dial is not a capture. Multiple captures 
arc handled correctly - if you move a piece by making a capture, your move will not be completed until all 
possible captures with this piece have been made. 

The standard rules of checkers apply. If a piece reaches the eighth rank of the board, it is promoted to a 
king; kings may move in any direction. A side wins cither by capturing all of die opposing pieces, or if the 
opposing side can make no legal move. 

When it is your turn to move, you may also use the right mouse button to select from a menu of options, 
which are described below: 

Redraw This causes die VGTS to redraw die entire board. This command should rarely be 

necessary. 

Pass (skip turn) This command can be used if you want die program to make the first move. You can also 
use diis to avoid any capturing obligations. 

Change search depth 

By default, the program searches 4 half-moves ahead when choosing its next move. That is, 
it considers its own move, your response to this move, its next move, and your response to 
that. The "Change search depth" command allows you to change die depth of lookahcad 
to any value from 1 to 8. Don't select any of die higher depdis unless you have a lot of 
patience, however. The program takes about 20s to respond to a typical opening move 
when the depth is 6, about 50s when die dcpdi is 7, and about 3 minutes when the depth is 
8. (These limes were taken on a 10 MHz SMI workstation - Cadi i net will be slightly 
slower.) Note that you may find out die current search dcpdi by selecting "Change search 
depth", and.then clicking outside die "depth' menu. 

Edit board This command puts you into Edit mode, which allows you to cheat by adding pieces to, or 

removing pieces, from, the board. Edit mode is described below. 

Back up one movcThis allows you to retract (eg. to correct) your last move. 

Resign The quick and cowardly way to end the game. 

The program chooses it's move by performing a .'brute-force' search, using alpha-beta pruning. It evaluates 
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the board positions at the 'leaves' of the search tree using a simple heuristic based on the number and position 
of pieces on each side. A 'value indicator' to the right of the board indicates the value of the current position, 
as seen by' the program. (If the indicator is above the halfway mark, for example, then the program 'thinks' 
that you arc winning.) There are also counters immediately above and below the value indicator, giving the 
number of pieces on each side. The value indicator and the piece counters arc updated whenever the program 
completes its move. 

You can make changes to the board (between moves) in Edit mode. In this mode, a special menu is 
displayed to the right of die board. To add a piece to die board (or change an existing piece), click the square 
in the menu that contains that piece. You may place a copy of this piece on any (shaded) square of the board, 
by clicking that square. You may do this repeatedly; it is not necessary to select from the menu each time. 
Note that you use the 'empty square' to delete one or more pieces from the board. You may remove all pieces 
from the board by clicking "Clear". When you have finished making changes to the board, click "Done" to 
leave Bdit mode. It will still be your turn to move next. 

Mail comments and/or gripes to Ross Finlayson - rsf@diablo. 
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Fscheck: File System Checking Program 



This program is a file system disk checker as well as simple file system editor that can be used to inspect and 
modify file system disk data structures. In addition, it gives one the capability to create and initialize new file 
systems. Fshcck must only be used when there is no other file system activity. It also should only be used by 
persons responsible for maintaining the file system. 

11.1. Invocation 

One can invoke fscheck from within the V system executive by typing 

fscheck 

or 

fscheck devkename 

If no device name is specified, fscheck attempts to open two devices, [dcvicc]diskO and [dcviccjdiskl. Non- 
existence of a second device docs not affect correct operation of the program. Note that the devices must be 
attached to the workstation from which the command is invoked and die kernel running on the workstation 
must include the proper disk driver (sec the Kernel Section for details on which kernel should be booted). 

1 1 .2. Commands 

Commands arc provided to check the global data structure consistency of each file system, inspect and 
modify individual node descriptors (ND), and initialize new file systems. 

a[+r] [ +s ] C hcck the consistency of the file system block allocation. If +r is specified, the bitmap is 

reconstructed. If +s is specified, error messages about blocks marked in the bitmap but 
not allocated to a file arc suppressed. 

b block print the nd number of all node descriptors that point to the given block number. 

Normally, there is at most one. If the allocation is inconsistent, a block may be allocated 
more than once. 

c update the checksum in the current ND, print it, and set the current field to the checksum 

field. 

f print the pathname of the current ND relative to the file system being checked. 

g field set die field corresponding Ur the given name as the current field and print the current 

field. 

i initialize file system information. Prompts the user for the name, drive number, stari 

block, and length of each file system in the disk subsystem and writes the information intc 
the file "fstab" on the root file system. Note that die start block of the first (root) file 
system should correspond to the START_FD_KILH definition (usually 40) in 
W/scrvcrs/storagc/storagcdcfs.h". Warning: this command should only be cxccutcc 
when new file systems are being created. 
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q 

s number 

t 

w 



1 print all links from and to the current ND. 

n <path> | <nd> set the ND corresponding to the given pathname or number to be the current ND. 
Pathnames must be specified as absolute pathnames (i.e. starting with "/"). If a pathname 
cannot be followed, the current ND is set to the last node visited while looking up the 
pathname. This occurs if the node docs not exist or the path from the root cannot be 
followed (e.g. a node in the path has a bad checksum). 

p print all the fields of the current ND. 

quit. 

set the current file system to be the one indicated by number. 

check the consistency of the file system tree structure. 

write the current ND back to disk. The ND number is taken from the current value of the 
number field. If the current ND describes an allocated node (i.e. its name field is not. the 
null string), it is written only if its checksum is correct. If it describes an unallocated node, 
- it is written unconditionally. Checks that the number field is correct before writing die 
current ND out. 

<RHTURN> advance to the next field and print its name and value. Hitting <RETURN> after an V 
command prints the first field. 

print the current field. 

t set the current field to the previous field and print it. 

= <numbcr> | <str> 

store the given number or string in die current field and print it. The number may be 
decimal, octalfO' prefix), or hcxadccimaKT prefix). A string is a sequence of characters 
and must be enclosed by double quotes. A null string is represented by "". Strings are 
accepted only when the name field is being modified. Note diat modifications arc not 
effective until a "w" command is issued. 

1 1 .3. Initializing a new disk subsystem 

Once die disk drivc(s) have been formatted (using diskdiagX die characteristics of each of die multiple 
possible file systems should be specified. This can be accomplished by creating die root file system (as 
described below) and subsequently running the "i" command. Then, using the "s" command to successively 
switch to each new file system, the rest of die file systems should be created. 

1 1 .3, 1 . Creating a new file system 

To build a new file system, one should allocate blocks to the ND file (ND I) and to the bitmap file (ND 2). 
(If the file system being created is die root file system then a single block should be allocated to "fsuib" (ND 
3).) This is done by modifying dicsc node descriptors so that each refers to non-overlapping extents of disk 
blocks. Also, die link fields in each node descriptor should be updated so diat a proper tree structure exists, 
i.e. ND 2 is die son of ND I and ND 3 is die brother of ND 2. 4 After diis is done, a "t" command should be 
used to check die consistency of the new tree structure, and an "a +r" command must be issued so diat die 
bitmap reflects these newly allocated blocks. 



4 In the near future, the task of creating a new file system will be automated. 
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1 1 .4. Checking file system integrity 

Once the "s" command has been used to set the current file system to the one you want to check, test the 
consistency of block allocation using the "a" command. Used with the +r option, it rebuilds the bitmap file 
in the case of missing blocks (i.e. blocks marked as allocated in the bitmap but not actually allocated to any 
file) or blocks allocated to a file, but marked as free in die bitmap. Blocks allocated more than once have to 
be handled manually. In this case, use the "b" command to determine to which ND's they arc allocated. Use 
the V and the T commands to determine the pathnames of those ND's. Make copies of the conflicting 
files and remove the old ones. Note that the information in the files may be damaged. 

Second, check the tree structure using the "t" command. If there are missing links, find out what they 
should be using V and "1". If there are nodes completely disconnected from the file system, remove diem or 
else determine from their father pointers where they should be in the tree structure. The easiest way to 
remove a disconnected node is to mark the corresponding ND as unallocated (setting the name field to the 
null string) and then using "a + r" to recover the blocks that were allocated to diat file. 
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Standalone Commands 



This chapter discusses standalone programs, i.e.,, programs that do not run under the V kernel, that are 
useful with the V-Systcm. 

12.1. Vload 

Vload is the V-System bootstrap loader. The Vload program loads the V kernel and initial team into 
memory and starts up the kernel. ' 

There arc several versions of Vload. Currently, all versions use the V I/O protocol and V IKC protocol to 
load programs over the Kdicrnct. 5 On the Sun-l, die Sun 3 Mbit Kthcrnct board and lixcclan 10 Mbit 
Ethernet boards are supported as boot devices. On the Sun- 1.5 and Sun-2, the 3Com 10 Mbit Kdicrnct board 
is supported. 

Vload determines the files to load and other actions to take at run time, depending on what was typed on 
the command line and what information is stored in the configuration database for the workstation being 
booted (sec section WORKSTATIONCONHG). For each of its parameters, Vload gives first priority to 
command-line information, if any, second priority to the defaults for this workstation recorded in the 
configuration database, if any, and third priority to a default value determined at compile time. 

Team and kernel filenames arc interpreted in the V-Systcm "[public]" context, unless, they begin with a 
square bracket In die latter case, the name inside brackets is taken as a machine name, in the same name 
space used by the login command. If "#" is given as the kernel file name, no kernel is loaded. Instead, die 
file specified as first team is loaded into the kernel's memory area and executed as a standalone program. 

Besides file names, two other parameters arc also required: "world" and "options." The world may be 
cither V (production) or xV (experimental). The only option currently recognized is % b\ which causes a break 
to the prom monitor before the kernel is started. 

The following sections describe the defaults and special characteristics of die Uircc versions of Vload in use 
at Uus writing. 

12.1.1. 3 MbitEthemet 

This version of Vload is intended for booting Cadlinc, SMI Sun-l, and other Sun-l workstation 
configurations with 3 Mbit Sun Kdicrnct boards. These workstations ordinarily use a version of die Stanford 
PROM monitor that incorporates PUP bootstrap code. The first, step in booting these workstations is to load 
Vload using the bootstrap pkoms. This can be done by typing a keyboard command (b filename for SMI 
workstations, n filename for others), or automatically on powemp or reset (sec below). 

For tiicsc workstations, die kernel resides from 0x1000 to 0x10000, and teams arc loaded at Ox 10000. 

The compilcd-in default values for Vload's parameters in this version arc as follows: 

world Vtcam 



5 In the near future, ihcre will be a version of Vload lhat can boot a filcscrvcr machine directly from its local dusk. 
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tcaml-vgts kernel 
Vkerael/sunl+cn options 
null 

The only command line information visible to Vload is the name it was invoked under. Therefore, Vload is 
installed under several different names, and its action depends on its name. The names and actions arc listed 
below. 

V When called under this name, Vload will load the team teaml-vgts and the default kernel 

for this workstation, using the default options. The team and kernel arc loaded from a V 
storage server (production versions) rather than an xV storage server (experimental 
versions), that is, the world parameter is set to V. 

VV The team is teaml-sts, and the world is V. 

xV The team is teaml-vgts, and the world is xV, 

xVV The team is team I -sis, and the world is xV. 

Vload The user is prompted for team, kernel, and options. The default value is used for any field 

where the user enters a blank line, The world is V. 

x Vload Same as Vload, except that the world is set to xV. 

null If the name is null, Vload assumes it was autobootcd. Default values arc used for all 

parameters. 

others If a copy of Vload is installed under any other name, it will use its name as the team name 

to be loaded, set the options to null, and use defaults for the kernel and world. 

No special setup is required to get an SMI processor to autoboot-it will do so automatically 30 seconds 
after powenip or a k2 command. The PUP boot PROM requests boot file number 1 by number, which causes 
a file called l.Boot to be loaded from the first responding PUP RFl'P server. We have arranged for this flic to 
be a copy of Vload, so the boot action is as described under the null name above. 

A non-SMI processor can be made to autoboot by installing die proper jumpers in its configuration register. 
(Sec the Sun User's Guide for a full description of the configuration register.) Bits 7-4 of the configuration 
register arc an index into a tabic of bootfile names stored in the prom. An in-place jumper or closed DIP 
switch corresponds to a bit; no jumper or an open switch corresponds to a 1. These bits should be set to the 
number corresponding to the name "Vload." The "VV IT* command typed to- the PROM monitor causes it to 
list die bootfile names and corresponding numbers that it knows about. Vload is usually number 5, 
corresponding to jumpers on bits 5 and 7. Vload's action will be as described under the null name above. 

12.1.2. Excelan Ethernet 

This version of Vload is intended for booting Cadlinc, SMI Sun- 1, and other Sun-1 workstation 
configurations with Bxcclan 10 Mbit Kthcrnct boards. Ordinarily, this version of Vload is used only with 
workstations using a special version of the PROM monitor lhat incorporates 'WW bootstrap code. The first 
step in booting liicsc workstations is to load Vload using the bootstrap proms. This can be done by typing a 
keyboard command, not described here. 

The compilcd-in default values for Vload's parameters in this version arc as follows: 

world V team 

tcaml-vgts kernel 

V kerne l/sunl+ ex options 

null 
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The only command line information visible to Vload is the name it was invoked under. Therefore, Vload is 
installed under several different names, and its action depends on its name. The names and actions arc listed 
below. 

xlnV When called under this name, Vload will load the team tcaml-vgts and the default kernel 

for this workstation, using the default options. The team and kernel are loaded from a V 
storage server (production versions) rather than an xV storage server (experimental 
versions), that is, the world parameter is set to V. 

xlnVV The team is teaml-sts, and die world is V. 

xlnxV The team is learn I- vgts, and the world is xV. 

xlnxW The team is teaml-sts, and the world is xV. 

xln Vload The user is prompted for team, kernel, and options. The default value is used for any field 

where the user enters a blank line. The world is V. 

xlnx Vload Same as Vload, except that the world is set to xV. 

others If a copy of Vload is installed under any other name, it will use its name as the team name 

to be loaded, set the options to null, and use defaults for the kernel and world. 

There is currently no way to autoboot a workstation with TFTP boot PllOMs. This limitation will be 
removed in the future. 

1 2.1 .3. 3Com Ethernet 

This version of Vload is intended for booting Sun-1.5s and Sun-2s with 3Com 10 Mbit Ethernet boards. 
These workstations boot using cither a local disk or tape, or the SMI network disk protocol. The network disk 
protocol docs not allow specifying a file name, so the V-Systcm ND boot server is only capable of loading one 
file- Vload. Vload, however, can read the entire command line typed by the user. 

The compilcd-in default values for Vload's parameters in this version arc as follows: 

world V team 

tcaml-vgts kernel 
Vkcrncl/sunl J+cc options 
null 

Zero or more arguments may be passed on the command line to Vload. If the first argument to Vload is 
one of the special values described below, it is stripped off and the special action listed is taken. After this 
check, the first three remaining arguments arc respectively used to override die defaults for team name, kernel 
name, and options. Values set by these arguments have priority over values that may have been set by die 
first argument 

V Sets the world to V, and the team to (eaml-vgts. (This team name will be overridden by 

the next argument if present) 

VV The team is set to teaml-sts, and the world is V. 

x V The team is set to teaml-vgts, and the world is x V, 

xVV The team is set to teaml-sts, and the world is xV. 

null If no arguments arc present the default values arc used for all parameters. 

vmunix The SMI boot PROMs have this name hardwired in for autobooting, so it is treated the 

same as a null first argument. 
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others If die first argument is not one of these values, the default world is used, and the arguments 

present specify team name, kernel name, and options, as described above. 

12.2. Postmortem 

Postmortem is intended to provide some help in diagnosing system deadlocks, kernel aborts, and other 
disastrous errors. Any time the system seems to be hanging, you can break to the PROM monitor, and type the 
command 

n postmortem 
Substitute b for n on SMI workstations. 

Postmortem examines the kernel data structures left behind after a crash, and prints out the state of each 
process, if any exist, the pid of the currently aedve process, and the ready queue. 

It is important not to use the monitor ki or k2 command or press the workstation reset button before 
running postmortem. 'ITicsc actions cause memory to be cleared. The PROM monitor on a Cadlinc 
workstation will not operate properly if die mouse is active, but fortunately, it is possible to turn off the mouse 
without power cycling the workstation by unplugging the keyboard and plugging it back in. 'lTiis should not 
be necessary if you were able to press the comma key on the numeric keyboard while the kernel was still 
running. 

12.3. Ipwatch 

The ipwatch family of programs provide a way of monitoring the Ethernet to debug protocol 
implementations or search for the cause of strange behavior. Ipwatch knows about most common types of 
packets seen on the Stanford network, including most PUP protocols, Internet protocols such as IP, TCP, and 
ICMP, XNS protocols, and the V intcrkcrncl protocol. It can print packet traces on die screen, or save them 
in a file. Knwatch is a version for the Sun 3 Mbit Ethernet board, while ecwatch works on the 3Com 10 Mbit 
board. Kxwatch works with the Excelan 10 Mbit board. 

To run enwatch, reset the workstation completely, and type the command 

n enwatch 
for Cadlinc workstations, or 

b enwatch 
for SMI workstations. The program is menu driven, and most options arc self-explanatory. 

Currently, all versions of ipwatch use the PUP Leaf protocol on the 3 Mbit Kthcrnct to write packet traces to 
files, and they run only on the Sun-1 with Stanford PRO Ms. 

12.4. Diskdiag 

'Hie diskdiag program is a diagnostic program Uiat allows one to manually access specific sectors on the 
disk. It is useful for verifying the correct interaction between the disk controller and disk drives, as well as for 
initializing a new disk. Diskdiag is configured to run on a system with a Xylogics 450 or Interphase 2181 disk 
controller and Fujitsu M2351 and M2284 disk drives. 

To run diskdiag, type the command 
b ec() diskdiag 6 



6 Somc SMI workstations with older PROM revisions require thai nd() be used in place of cc(). 
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for SMI workstations, or 

n diskdlag 

for Cadlinc workstations. There arc commands available to format(f), read(r), seek(s), and 
wp1 te(w). The user hi prompted, as necessary, for more information on each of these commands. 

In addition, it is possible to label ( 1 ) a drive with die configuration parameters needed by the disk driver 
in the kerne!. Executing the format command automatically labels the disk after the format is complete. The 
ve p 1 f y ( v ) command reads die label off of disk and prints it on the console. 

The partitlon(p) command prompts the user for the start block and length of each partition on the 
disk and creates a disk partition table. Existence of a disk partition table is optional as it is not needed by any 
system software. The examl ne('x) command allows one to examine the contents of the disk partition table. 

Reinitializing the diskdiag program is accomplished using theagaln(a) command. 

1 2.5. Offload and Off!oad38 

The offload program uses PUP RFTP to load standalone programs into a Sun-1 equipped with a Sun 3 Mbit 
Ethernet interface, at a user-specified memory location. This program is useful on Sun-l workstations 
equipped with standard Stanford PUP boot PROMs, because they arc only capable of loading programs that 
reside at the default address of Ox 1000. 

To use offload, first reset the workstation, then give the command 
n offload 
to the .Sun PROM monitor. (Substitute 'b' for V on SMI workstations.) The program will prompt for 

LThc name of the program to be loaded. The default directory is the miscscrvcr's standard default 
directory, as described under Vload. 

2. Hie load origin of the program, in hex. This should be the same value specified to cc68 or !d68 with the 
-T option when the program was linked. Offload will refuse to load a program that would overlap part 
of the memory it uses; use offload38 if this is a problem (sec below). 

3. Where to put a copy of the program's b.out header. This is usually not needed; enter '0' to omit it. 

4. Whether to load the program's symbol table into memory. This is generally not needed. Sec the Sun 
User's Guide for a description of how program symbol tables appear in memory. 

5. Whether to jump to the program's entry point or return to die PROM monitor after the program is 
loaded. After returning to the monitor, the command 

g 1000 

will restart offload to load another file. 

Offload itself resides at 0x1000 so that it can be loaded by the PROM monitor. If it is necessary to load a 
program thai would overlap offload's default location, use offload to load oJ]had38 at 0x38000. This program 
is identical to offload except for its starting address. The command 

g 38000 

will restart offload38 after a return to the monitor. 

The following dialog can be used to load a nonstandard kernel that is too large for Vload. User input is 
underlined. 
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> n offload 

Sun Offset Loader ■- Version 2.2 - 2 Feb 1983 

Loader resides from 1000 to 60e8 

Program to load: off1oad38 

Origin (hex): 38000 

Place b.out header at (hex; 1f not needed): & 

Load symbols? (y/n): ji 

Execute? (y/n): y. 

Sun Offset Loader - Version 2.2-2 Feb 1983 

Loader resides from 38000 to 3e0e8 

Program to load: /usr/sun/ Vboot/teaml-sts 

Origin (hex): 10000 

Place b.out header at (hex; if not needed): ffeO 

Load symbols? (y/n): a 

Execute? (y/n): n 

> q 38000 

Sun Offset Loader - Version 2.2-2 Feb 1983 

Loader resides from 38000 to 3e0e8 

Program to load: vour nonstandard kernel 

Origin (hex): \QQQ 

Place b.out header at (hex; 1f not needed): ffcO 

Load symbols? (y/n): n, 

Execute? (y/n): y, 

Using "/usr/sun/Vboot/tcaml-sts" as above loads the standard version of the plain exec. You can 
substitute tcaml-vgts or your own special first team. 
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Part II: 
Program Environment 
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Program Environment Overview 

This manual, the V-System Program Environment Manual describes the execution environment provided 
for C programs written to run in the V system (and in particular the V kernel), primarily for programs in the 
C language. This program environment is designed to minimize the difficulty of porting C programs (and C 
programmers) from other C program environments, such as that provided by UNIX 7 , and to provide access to 
the distributed process and message facilities provided by the V kernel and V servers. 

The program environment consists of three major components: 

• The base C language implemented by the compiler. 

• Routines that arc part of die C program library in most C implementations. 

• Functions that access V facilities. 

The basic C language is not described here. The reader is referred to The C Programming Language by R W. 
Kcrnighan and D. M. Ritchie, Prentice- Hall 1978 for a tutorial on the language and standard C library 
routines. 

Standard C library routines are only described here to die degree they differ in the V program environment 
from other implementations, particularly the Unix C library. The reader is referred to die above-cited book 
or The Unix Programmer's Manual for details on these standard functions. 

The V-spccific functions arc described in detail in the following chapters. 

While there has been a strong attempt to provide a superset of the standard C program environment, there 
is no real definition of "the standard C program environment." While C as a programming language docs not 
define I/O facilities, memory management, etc., an ill-defined dc facto standard has arisen from the extensive 
use of C with the Unix operating system. Attempts to port C programs have resulted in a slightly more 
portable standard program environment Uian originally used with Unix. However, there is not, to die 
authors' knowledge, a definition of what a portable C program can reasonably expect of its program 
environment. The functions included in the V program environment for C, excluding V and SUN 
workstation specific routines, constitute our proposal for such a standard portable C program environment. 

The differences between the V C program environment and die Unix C program environment fall into four 
major categories 

• Functions that are Unix system calls which may be provided as V library routines, e.g., sUme(). 

• Functions that arc slightly changed in Uicir implementation, but provide (essentially) the same 
functionality, e.g., malloc(). 

• Functions that arc SUN workstation-specific, because they arc not necessary in standard Unix on, say, a 
VAX 8 . For example, die long division routines arc in tliis category, as arc the emulator traps, 

• Functions that are particular to the V-Systcm, like CrcatcQ and ReadyQ. 



7 
unix is a trademark of Bell Laboratories. 

a • 

v/vx is a trademark of Digital Equipment Corporation. 
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13.1 . Groups of Functions 

The description of functions is structured by subdividing them according to functional groups as follows, 
emt 



exec 

fields 

io 

math 

mem 

naming 

numeric 

process 

strings 

time 

vgts 

others 



C language interface to the on-board PROM monitor emulator traps. See the Sun User's 
Guide for more information. 

V-Systcm program execution functions. 

Functions that enable a pad to be used as a menu, similar to a data entry terminal. 

Input/output related routines. 

Mathematical functions. 

Memory management and allocation routines. 

V-Systcm name management functions. 

Arithmetic and numeric functions. 

V-Systcm process service functions and V kernel traps. 

Character string manipulation routines. 

Clock and time conversion services. 

Virtual Graph'cs Terminal Service interface routines. 

Miscellaneous other functions. 



This functional subdivision is also reflected in the structure of the program source for the V C library, where 
every subdivision corresponds to a subdirectory of die C library directory. 



13.2. Header Files 

The following header files define manifest constants, type definitions and structs used as part of the V C 
program environment. They arc included as usual by a "# include <hcadcrnamc>" directive in C programs. 

Standard header file for V kernel types and request/reply codes. 

Ethernet-specific header information. This is very low-level information; most users will 
want to use the network server instead. 



Vcnviron.h 
Vcthcrnct.h 

Vcxccptions.h 
Vgts.h 

Vio.h 

Vmousch 

VneLh 

Vproccss.h 

Vscrial.h 



Exception types and exception request format 

Virtual graphics terminal server interface. This should be included in any programs that 
do graphics. 

I/O Protocol header file. Types and mode constants for file manipulation functions 
described in chapter of this manual; 

Mouse device-specific header information. Most programs will use the Vgts to handle 
graphics input. 

Network server definitions. This is included in any programs that use die network. 

Processor state structure and other process-specific header information. 

Manifests for the serial lines. Again, very low level for most users; use the higher level 
library interface instead to be more portable. 
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Vscssion.h Manifests and message structs for session services. These arc remote servers, often called 

Unix or V servers, that provide transparent file access over a network. 

Vtcams.h Team, header file. Structures used to communicate with the team server and to pass 

information to teams when they are created. 

Vtime.h Structures used in time services, primarily for getting time from a session server. 
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Program Construction and Execution 

A V-System C program is constructed and executed similar to a C program on Unix. 

14.1. Writing the C Program 

An application program on the V-Systcm starts to execute as a single process 9 , with priority 4. It is allocated 
an initial stack area of about 4000 bytes, just above its uninitialized data segment. If this is not large enough, 
one of the first actions of the team's root process should be to use the CrcatcO library function to create 
processes with larger stacks. 

Note that large dynamically allocated areas of memory should be allocated using malloc, calloc, or a similar 
memory allocator, and not be allocated on the process stack. Warning: There is no run-time checking for 
overflowing the process stack allocation. The program behavior from stock overflow can be sufficiently 
bizarre as to cause good programmers to seek refuge in monasteries. If the stack overflow caused the process 
in question to get an exception, the standard exception handling routine will usually detect the overflow and 
print a message; however, not all stack overflows cause an exception in the process that generated them, and 
sometimes the stock is back in bounds by the time the exception occurs. 

The file Vcnviron.h is a header flic defining the types and constants diat arise as part of the interface to the 
kernel. It is included by the line 

^include <Venv1ron.h> 
Other V header files, listed in the previous section, are included similarly. 

14.2. Compiling and Linking 

When die application program is compiled and linked, references to kernel operations and other standard 
routines must be resolved by searching the library file libV.a (kept in /usr/stin/lib on Stanford Unix 
systems). The application must be relocated so that its text segment starts at 0x10000. These defaults arc 
automatically selected with the -V option of the cc68 command. The compile command: 

cc68 -V -p progpamfna 

produces a .r file for running with the kernel. The program environment provided by the libV.a library is 
given in the later sections of this manual. 

14.3. Program Execution 

There arc two models for executing V C programs, namely: using the V executive and bare kernel mode. 



9 Eor a complete discussion of processes, message passing, and other services provided by the V kernel, sec the kernel manual. 
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1 4.3. 1 . Execution With the Executive 

Use of the V executive is described in the V-Systcm commands manual. Basically, one types the name of 
the file containing the program to the command interpreter followed by zero or more command arguments. 
The program is then loaded and executed. 

When the V executive is used, the program execution begins at a procedure called ma1 n( ), passed a count 
of the number of arguments to the program and an array of pointers to the program string arguments, as 
given on the command line. Each new team is passed standard input, output, and error files through the 
Team Root message. 

The following example shows how a program can read its command line arguments. The variable argc 
contains the number of arguments including the command name. The arguments are kept in argv[0] 
through argv[argc-l]; the command name is argv[0], argv[l] is the first argument, 
argv[argc-l] is the last argument, and argv[argc] is null. This matches the Unix convention. 

main( argc, argv ) 
1nt argc; 
char *argvC]; 
/* Echo arguments V 

{ 

1nt 1; 

for( 1-0; 1 < argc; ++1 ) 

pr1ntf( "%s ". argvCI] ): . 
putchar("\n") ; 

} 
The executive sets the new team's team priority to 30. 

14.3.2. Bare Kernel Mode 

In bare kernel mode, execution also begins at main(), but no arguments arc available. 

None of the standard servers ordinarily included in the V executive arc available, unless the program 
includes one or more of them itself (as described in the V servers manual). 

A program to be executed in bare kernel mode is loaded by a special loader program called Vloacl: 

n Vload 

typed to the SUN monitor causes it to load and execute the loader. (Use b in place of n on SMI 
workstations.) Vload then prompts for the name of a file containing the program. The use of this loader is 
described more fully in the Standalone chapter of the V commands manual. 

14.4. The Team Root Message 

Kach team is passed a team root message at the time it is started. This is die message passed to the team by 
Uie Reply () call that sets it running. The team root message is a structure oftypc RootMcssagc, ;is defined 
in die standard header file <Vteams.h>. A function called TeamRoot() (automatically included in every 
program by die -V option of cc68) receives the team root message, stores a copy of the team root message in 
an area pointed to by the global variable RootMsg, initializes die team's standard i/o, and calls main( ). If 
ma1n() returns, TeamRoot() calls ex1t(). The team root message can be accessed from within a team 
(not usually necessary) by declaring it as 

extern RootMessage *RootMsg; 
The team root message contains the following fields: 
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stdinserver- Process id of the server providing this team's standard input file. 

stdoutserver Process id of the server providing this team's standard output file. 

stderrscrver Process id of the server providing this team's standard error file. 

stdinfile Instance id of this team's standard input file. 

stdoutfile Instance id of this team's standard output file. 

stderrfile Instance id of this team's standard error file. 

rootflags A set of flags indicating whether the team is to overwrite or append to its standard output 

and standard error, whether standard input, output, or error have been redirected, and 
whether it is to release its standard input, output, or error instances upon exit. 

namescrver Process id of the server providing the team's initial current context (i.e., current working 

directory). 

contextid 'Hie context id of the team's initial current context. 

kcrncipid Process id to which the team is to send to obtain secondary kernel services (sec the V kernel 

manual). Normally the same as the team creator's kernel pid, provided the new team is 
running on the same workstation as its creator. 



14.5. The Per-Process Area 

Each process has a region of team memory reserved for its own use, called its stack space. On the Sun, a 
process's stack grows downward from the highest address in this region. A portion of the stack space, called 
the per-process area, is used to store a few process-global variables. On the Sun, this area begins at die lowest 
address of the stack region. A team-global variable called PerProcess points to this area. It is reset by die 
kernel to point to the correct area on every process switch. 

The standard per-process area is described by the PcrProccssArca structure in the header file <Vio.h>. It 
contains the following values: 

stdio An array of three File pointers describing die process's standard input, output, and error 

files. <Vio.h> defines die macros stdln, stdout, and stderr to be PerProcess-> 
std1o[0], PerProcess->std1o[l], and PerProcess->std1o[2] respectively. 
Note that only pointers, not the Kile structures Uicmsclvcs, arc kept in die per-process 
areas. 

namescrver Process id of die server providing the process's current context. 

contextid Context id of die process's current context 

stackSize 'lTic size of the process's stack space, in bytes. 

The TeamRoot( ) function initializes the team root process's per-process area from die values passed in the 
team root message. 'Hie Create () library function, used to create new processes, initializes each new 
process's per-process area to be a copy of that of its creator (except for die stackSize field). This causes each 
child process to inherit its creator's standard I/O and current context 
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— 15 — 
The V-System Configuration Database 



15.1. Introduction 

When a diskless workstation boots up, it has a limited amount of information about its own configuration 
and identity. A boot program can probe to see what devices are attached, and some workstations may have 
configuration registers, additional switches, or a small amount of nonvolatile memory. If a workstation has an 
Ethernet board, there will be a PROM or DIP switch on the board containing its Ethernet address. There 
may also be some machine-specific information in PROMs on the processor board. If the workstation is 
booted by typing a command, rather than automatically on power-up, the user may be asked to type in some 
information. 

From this information, the workstation software needs to deduce several things, including at least: 

1. What version of the kernel to load (68000, 68010). 

2. Which Ethernet board to use for interkerncl communication, if there is more than one. 

3. What to run as the initial team. 

4„ Whether to run the VGTS, the STS, or some other program as the terminal server. 

5. What commands to execute before turning control over to the user, if any. (For example, we may wish 
to run a print server on this workstation, or automatically bring up an internet server in the 
background.) 

6. What Internet address to use for this workstation. 

7. What the name of this workstation is (e.g., SUN-MJ402). 

8. What type of terminal is connected to the workstation, if the STS is to be used, 

In general, there is no reliable algorithm for determining most of these things. In fact, many arc the result 
of essentially arbitrary human decisions- for example, die workstation name. 

15.2. Configuration Database 

As a solution to this problem, die V-Systcm maintains a configuration database, containing information 
about each workstation. The information is organized as sets of key word/ value pairs, one per workstation. 

'Hicrc is one standard library function provided for extracting information from die configuration database: 



SystemCode QueryWorkstat1onConfig(keyword, value, maxlength) 
char 'keyword, *value; 
1nt maxlength; 

Given a character string representing the keyword, diis routine returns the corresponding value as another 
character string. The variable keyword points to the keyword, value points to the place to put die value, 
and maxlength is the si/.c of die buffer, which should include space for a terminating null byte. The routine 
returns a system error code if there is no configuration information recorded for die querying workstation 
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(NOT FOUND) there is some configuration information, but no value corresponding to the given keyword 
(BADARGS) or the buffer was too short to hold the value (BADJiUFFER). else returning OK. In the 
buffcrtoo-short case, it will return as much as there is room for. In unusual situations, other error codes may 
be generated; these can be treated as failures or considered equivalent to NOT_FOUND. 

15.3. Implementation 

Ordinarily programs should not be aware of the implementation of the configuration database; this 
implementation may change in the future. The QucryWorkstationConfigO function should be the only 
interface used. Since there is no standard library function provided to modify the configuration database, 
however system maintained need to be aware of its implementation. The current implementation allows the 
configuration database to be modified with an ordinary text editor, and the changes installed with the same 
tools that are used for installing new binary program images on storage servers. 

The V configuration database is currently implemented as a set of configuration files, one for each 
workstation. Each configuration file must be available on every publically-available V storage server, 
requests from nonlocal clients.) 

The name of each workstation's configuration file is derived from its hardware Ethernet address- a 
convenient unique identifier. 11 The files arc kept in a subcontcxt named "config", under the server's public 
context. (See section 30.) For a workstation with Ethernet address 0260.8c0 1.9954 (a typical 3Com-assigncd 
address), the configuration file could then be read by a workstation as a file named 
"[public]config/C.02608c019954"; this is in fact how QucryWorkstationConfigO is implemented. 

A configuration file is an ASCII text files, consisting of a set of keyword/value pairs, arranged in no 
particular order. Each keyword appears at the beginning of a new line, and is separated from its 
corresponding value by a colon (Y). A line beginning with a colon serves as a continuation of the value on 
the previous line. This format has been designed to be easy to read and easy to parse. (Note that spaces both 
before and after the colon may be considered significant by programs, so take care when creating or editing 
config files.) 

At Stanford, the master copies of configuration files arc kept in the directory /xV/config on Pcscadcro. and 
only dwsc copies should be edited. The command "make install" (run as user ds) is used to install changes. 

Currently Defined Keywords 

The following keywords are in use at this writing. A list of keyword names and their meanings is presently 
kept in the same directory as the config files themselves, in a file called "keywords." 

name The name of this workstation. Should match the name used in local IP name tables for this 

workstation's IP address. Iticrc is no default 

ip-addrcss The workstation's Internet Protocol address, given in the conventional [a.b.c.dj notation, 

where a, b, c, and d arc decimal integers. On the 3 Mbit Ethernet, the default value of d is 
the 8-bit Ethernet host address, while default values of a, b, and c arc determined by the 
Internet server. For 10 Mbit Suns, this keyword should always be present 

ip-gatcways Name of a file containing a list of Internet gateways to be used by this workstation. The 

file name is given relative to the standard [public] context If this keyword is omitted, the 
Internet server will not forward datagrams through any gateways, i.e., only local traffic will 



10 Publicaily-availabtc storage servers arc defined as those dial respond to GctPid(STORAGE - SERVER, ANY- PID 

13 Currently, on Sun-2 workstations with 3Com Ethernet interfaces, the address assigned to the Ethernet board is used, not the address 
assigned to the processor. 
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kernel 



team 



world 
boot-options 

startup-script 



alt-ether-addr 



ndboot 



terminal- type 



be supported. 

Filename of the program to be loaded as the kernel, for use by Vload. The name is given 
relative to the standard [public] context If this keyword is omitted, Vload uses a compiled- 
in default, currently Vkernel/sunl+en for the 3 Mbit Ethernet version, Vkernel/sun2+ec 
for the 10 Mbit 

Filename of the first team, as above. If it is omitted, Vload uses a compilcd-in default, 
currently tcaml-vgts. 

Either V or xV. Used by Vload. If omitted, Vload uses a compiled-in default currently V. 

Boot options for use by Vload. Currently the only option is b, meaning "break before 
starting kernel." The default is a null string. 

Filename of the startup script Currently used only by tcaml-scrvcr, for workstations that 
autoboot as servers. No default In the future, the definition of this keyword will be 
changed to allow the startup script to be placed directly in the config file, and all (or most) 
versions of the first team will use it 

Alternate cthcrnct addresses for this workstation, one per line. These arc addresses the 
workstation may use, other than the one the config file is named for. 10 Mbit addresses 
should be given in hexadecimal, in die form xxxx.yyyy.mz. 3 Mbit addresses may be 
given in octal. The default is null. This keyword must be present for use by the Vax Unix 
ND server for workstations that boot using the ND protocol under a different Ethernet 
address than the one the config file is named for. This is true of SMI Sun-2's with PROM 
revision N or later. 

The Vax Unix ND boot server looks for a configuration file when deciding whether it 
should answer boot requests, and will refuse to respond if there is none or it contains the 
line "ndbootno". (This procedure allows our ND server to coexist with SMI Network 
Disk servers on the same net) Thus, the default value for this option is "yes" if a config 
exists for this workstation, otherwise "no." 

Type of terminal used as a console. Used by the STS. The default is to assume the 
Stanford PROM terminal emulator for Cadlincs, or something ANSI-compatible (like the 
SMI PROM terminal emulator) otherwise. The only other recognized value for this option 
is "h!9". 



Usage 

In general, we have implemented programs that use this service in such a way that if a configuration file or 
specific keyword/value pair is missing, some reasonable default is used where this is possible. Also, where it 
is easy to reliably determine something by examining the hardware present it is best to do that instead of 
putting the information in the configuration file. Following these principles means that fewer updates to the 
configuration files arc needed to keep workstations running correctly when something changes. 

In some cases, the value of a keyword may be the name of a file, perhaps because it is more convenient for 
the client to read the information from a file, or because the information associated with die keyword is quite 
bulky. In the present implementation, such files arc kept in die "[p.ublic]config/" directory along with the 
configuration files themselves. Files whose names begin with "S." arc startup command scripts for 
workstations that boot automatically. Files whose names begin with "G." are gateway information files used 
by die internet server. 
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— 16 — 
Input and Output 



The input and output routines can be divided into three categories: 

1. Basic I/O routines like getchar() that arc supported but differ in their implementation from the 
standard Unix versions. 

2. I/O support routines like pr 1 ntf ( ) that are identical with the standard Unix version. 

3. V-specific I/O routines like Read() and Write() that are used in several cases to implement the 
standard C routines in the V message-based world. 

16.1. Standard CI/O Routines 

the following standard C I/O routines are available: 

chdir() c1earerr() fclose() feof() 

ferror() ff1ush() fgetc() fgets() 

fopen() fprintf() fputc() fputs() 

fread() freopen() fscanf() fseek() 

fte"M() fwrite() getc() getchar() 

gets() getw() printf() putc() 

putchar() puts() putw( ) rewind() 

scanf() sprintf() setbuf() sscanf() 
ungetc() 

However, fopen() returns a pointer value of type *Filc, where File is defined in <Vio.h> and is a totally 
dilTcrcnt record structure from that used by, for instance, the Unix standard I/O. Also, setbuf ( ) is a no-op 
under V. 

16.2. V I/O Conventions 

Program input and output arc provided on files, which may include disk files, pipes, mail-boxes, terminals, 
program memory, printers, and other devices. 

To operate on a file, it is first "opened" using Opon( ) if the file is specified by a pathname, otherwise by 
0penF1le( ) iflhc file is specified by a server and instance identifier. The mode is one of the following: 

FREAD No write operations arc allowed. File remains unchanged. 

FCREATE Any data previously assuciatcd with the described file is to be ignored and a new file is to 

be created. Both read and write operations may be allowed, depending on the file type 
described below. 

FAPPEND Data previously associated with the described file is to remain unchanged. Write 

operations arc required only to append data to the existing data. 

FMODIFY Existing data is to be modified and possibly appended to. Both read and write operations 

arc allowed. 
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Both open functions return a pointer to an open file descriptor that is used to specify the file for subsequent 
operations. C1ose( ) removes access to the file. Seek( ) provides random access to the byte positions in the 
file. Note: die value returned from a byte position that has not been written is not defined. 

Each program is executed with standard input, output and error output files, referred to as stdln, 
stdout, and stderr respectively. 

The file type indicates the operations that may be performed on the open file as well as the semantics of 
these operations. The file type is specified as some combination of the following attributes. 

READABLE The file can be read. 

WRITEABLE The file can be written. 

APPEND.ONLY ' „ 

Only bytes after the last byte of die data previously associated with the file can be written. 

STREAM All reading or writing is strictly sequential. No seeking is allowed. A file instance without 

the STREAM attribute must store its associated data for non-sequential access. 

FIXEDJ.ENGTH _, , 

The file instance is fixed in length. Otherwise the file instance grows to accommodate die 
data written, or the length of the file instance is not known as in die case of terminal input. 

VARIABLE.BLOCK ■ . 

Blocks shorter than the full block size may be returned in response to read operations other 
than due to end-of-file or other exception conditions. For example, input frames from a 
communication line may differ in length under normal conditions. 

With a file instance that is VAR1ABLE.BLOCK, WRITKABLK, and not STREAM, 
blocks that arc written with less dian a full block size number of bytes return exactly the 
amount written when read subsequently. 

MULTLBLOCK Read and write operations arc allowed that specify a number of bytes larger than the block 
size. 

INTERACTIVE The open file is a text-oriented stream. It also has die connotation of supplying 
interactively (human) generated input 

Not all of the possible combinations of attributes yield a useful file type. 

Files may also be used in a block-oriented mode by specifying FBI.OCK.MOnF. as part of the mode when 
opening the file. No bytc-oricntcd operations arc allowed on a flic opened in block mode. 

Sec the V-System Servers Manual for more details on the semantics of the various possible file types and 
modes. 

1 6.3. V I/O Routines 
1 6.3. 1 . Opening Files 

File *Open(pathname, mode, error) 

char *pathname; unsigned short mode; SystemCode *error; 

Open the file specified by pathname with die specified mode and return a file pointer for use with 
subsequent file operations. 
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mode must be one of FREAD, FCREATE, FAPPEND, or FMODIFY, with FBLOCK.MODE if block 
mode is required. If Open() fails to open die file, it returns NULL and the location pointed to by error 
contains a standard system reply code indicating die reason. If. an error occurs and error is null, Open( ) 
calls abort (). 

File *OpenFile(server, instancsidentif 1er , mode, error) 

Processld server; Instanceld instanceidentlf ier; 

unsigned short mode; SystemCode *error; 
Open the file instance specified by the server and Instanceidentlf ier arguments and return a file 
pointer to be used with subsequent file operations. 

mode must be one of FREAD, FCREATE, FAPPEND, or FMODIFY, with FBLOCK.MODE if block 
mode is required. If the instance is to be released when Close() is called on this file pointer, 
FRELEASE_ON_CLOSE must also be specified as part of the mode. If OpenF i 1 e ( ) fails to open the file, 
it returns null and the location pointed to by error contains a standard system reply code indicating the 
reason. If an error occurs and error is NULL, OpenFi le( ) calls abort( ). 

File •_0pen(req, mode, server/error) 

CreatelnstanceRequest *req; unsigned short mode; 

Processld server; SystemCode *error; 
Open a file by sending the specified I/O protocol request message req to the server specified by server and 
return a file pointer to be used with subsequent file operations. This Junction is only used when additional 
server-dependent information must be passed in the request message, or the file is to be opened on a server 
Uiat cannot be speci ficd by a character string path name asinOpen(). 

The request req may be cither a CreatelnstanceRequest or a QucrylnstanccRcqucst mode must be one of 
FREAD, FCREATE, FAPPEND, or FMODIFY, widi FliLOCKJvlODK if block mode is required. If 
_0pen<) fails to open the file, it returns null and the location pointed to by error contains a standard 
system reply code indicating the reason. If an error occurs and error is null, _0pen( ) calls abort ( ). 

SystemCode CreatoInstance(pathname, mode, req) 

char 'pathname; unsigned short mode; CreatelnstanceRequest *req; 

Open die file specified by pathname in die given mode using die specified CreatelnstanceRequest, but do 
not set up a File structure for it. A Create! nstanccRcply is returned at die location pointed to by req. The 
function returns a standard system reply code, which will be OK if the operation was successful. 

16.3.2. Closing Files 



Close(file) 

File •file; 

Remove access to the specified file, and free the storage allocated for the File structure and associated buffers. 
If the file is WR1TEABLE and not in FBLOCK.MODE, the output buffer is flushed. 



Spec1alClose(f1le, releasemode) 

File *f1le; unsigned releasemode; 

Close the specified file, as in Close( ). If SpecialClose( ) releases the file instance associated with the 
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specified File structure, the release mode will be set to releasemode. C1ose( ) sets the release mode to 
zero. Sec the I/O protocol section of the V servers manual for a explanation of release modes. 

Releaselnstance(f1leserver, flleld, releasemode) 

Processld fUeserver; Instanceld fileid; unsigned releasemode; 

Close the file instance specified by fUeserver and flleld, using the specified release mode. This 
function is used only when there is no File structure for the given file. 

16.3.3. Byte Mode Operations 

The standard Unix functions mentioned above may be used on files opened in byte mode (i.e., not opened 
in FBLOCK.MODE). Several other functions arc also available on such files, as described below. 



1nt Seek(f1le, offset, origin) 

File *f1le; 1nt offset, origin; 

Set the current byte position of die specified open file to that specified by offset and origl n and return 
TRUE (nonzero) if successful. 

If origin is ABSJJLK or ABSJWTE, the byte position is set to the of f set-th block or byte in the file 
starting from 0. If origin is RKLJiYTK, offset specifics a signed offset relative to die current byte 
position. If origin is F1LE_KND, offset is the signed byte offset from the end of file. 

If the file is F1XED_LENGTH, an attempt to seek beyond the end of file causes Seek to return FALSE 
and the byte position to remain unchanged. The end of file position is one beyond the last byte written. The 
value of bytes in the file previous to die end of file Uiat have not been explicitly written is undefined. 

Seek() may not be used on files opened in block mode. SeekBlock() should be used on such files. 
Seek() isidcnticaltofseek(). 

unsigned BytePosit1on(f1le) 

File *f1le; 
Return the current byte position in die spccilicd flic. The value returned is correct only if die current byte 
position is less than MAXJJNSIGNRD. This function is identical to f tell ( ). 

Flush(fHe) 

File •file; 
Flush any buffered data associated with the file, providing it is WRITEABLE. Flushing a file causes local 
buffered changes to the file data to be communicated to die real file. If die file is in block mode or not 
WRITKABLE, no action is performed, lliis function is identical to ff lush( ). 

Resynch(fHe) 

File «f1le; 
Rcsynchronizc the next block to read and write in die file with the server. Any buffered bytes are lost. This 
operation is only valid for streams, and is only needed when Uicro is more than one File structure associated 
with a single file instance. This will happen, for example, if two teams arc sharing die same standard output. 
Normally it should not be needed for files used in a single team. 
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SystemCode Eof(file) 

File nils; 
Any of the byte mode read or write operations may return EOF (Exception On File) as a special value 
indicating an inability to read or write further in the file. Eof returns a standard system reply code indicating 
the nature of the exception. This may be a true end-of-file, i.e., the current byte position exceeds .the last byte 
position of the file, or some type of error. 

ClearEof(file) 

File *f1l8; 
Clear the exception on the specified file. This only clears the local record of the exception; it does not affect 
the circumstances that caused the exception to occur. See Eof ( ) . 

1nt Buf far Empty (1f He) 
File *file; 

Test whether or not a file's local buffer is empty. If this function returns TRUE (nonzero), the next getc( ) 
will cause an actual read. If it returns FALSE (zero), the next getc( ) will return immediately with a byte 
from the buffer. 

1 6.3.4. Block Mode Operations 

The following functions arc most useful on files opened in block mode. Unless otherwise noted, they may 
also be used on files opened in byte mode. 

unsigned Read(file, buffer, bytes) 

File *file; char *buffer; unsigned bytes; 

Read the specified number of bytes from die file starting at the beginning of the current block location of die 
file and store contiguously into the byte array starting at buffer, returning the actual number of bytes read. 

If the number of bytes read is less than the number of bytes requested, the reason is indicated by the 
standard reply code returned by Fi1eException( ). The number of bytes requested may not be more than 
the block size of the file (returned by BlockS1ze( )■> unless the file has the type attribute MUU'LNLOCK. 
Read(') is intended for use on files opened in block mode only. Note: Read() docs not increment the 
current block number stored in the File structure for die given file. 

unsigned Wr1te(f1le, buffer, bytes) 

File *f1le; char *buffer; unsigned bytes; 

Write die specified number of contiguous bytes from the buffer to the file starting at. die beginning of the 
current block location of die file, and return the actual number of bytes written. 

The number of bytes to be written must be less dian or equal to the block size (as returned by 
B 1ockS1z9( )) unless the file has the type attribute MULTIJ1LOCK. If die number of bytes written is less 
than the number of bytes requested, die reason is indicated by the standard reply code returned by 
F11eExcept1on(). 

Write() should be used only on files opened in block mode. Note: Wr1te( ) docs not increment the 
current block number stored in the File structure for die given file. 
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unsigned B1lcsI'nF11e(f11e) 
File *f11e; 

Return the number of blocks in the specified file. Meaningful if the file is FIXED.LENGITI or is a 
WRITEABLE non-VARIABLE„BLOCK, STREAM file. 

unsigned BlockPos1t1on(f lie) 

File *f1le; 
Return the current block position in the specified file. 

SeekBlock(f1le, offset, origin) 

File «f1le; int offset; 1nt origin; 
Set the current block position of the specified open file to that specified by origin and offset. The new 
block position is the block offset from the specified block origin, origin is one of FILEJ5EG INNING, 
Fll.E_.END or FILE_CURRENT_POS. 

unsigned BlockS1ze(f1le) 

File *f1le; 
Return the block size in bytes of the specified file. 

unsigned F1leExcept1on(f lie) 

File 'file; 
Return the standard reply code indicating the last exception incurred on the specified file. This is used 
primarily on files opened in FBLOCK.MODE. Eof ( ) is used on byte-oriented files. 

16.3.5. Server-Specific Operations 

This section describes routines in. the I/O library which arc specific to particular servers. 

SystemCode CreateP1peInstance(read0wner, wrlteOwner, buffers, reply) 

Processld readOwner, wrlteOwner; 1nt buffers; 

CreatelnstanceReply *rep1y; 
Interact with the pipe server to create a pipe, with the specified owners for the reading and writing ends of the 
pipe, and the specified number of buffers, buffers should be between 2 and 10 inclusive. The reply to the 
create instance request is returned at die location pointed to by reply: it contains the file instance id of the 
writcablc end of the pipe. The id of the readable end is equal to this value plus I. 0penF1le( ) may be used 
to set up File structures for cither or both ends of the pipe. CreateP1peInstance( ) returns a standard 
system reply code, which will be OK if the operation was successful. 

File •OpenTcp(localPort, forelgnPort, forelgnHost, active, 
precedence, security, error) 
unsigned short localPort, forelgnPort; unsigned long forelgnHost; 
1nt active, precedence, security; SystemCode *error; 

Interact with the Internet server to create a TCP network instance, and return a pointer to a File structure 
opened in byte mode that can be used to send data .on the corresponding TCP connection. 
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To obtain a second File structure that can be used to read from the connection, use the call 

f2 * 0penFne(Fil8Server(fl), FHeld(fl) + 1, 
FREAD. +.FRELEASEJ3N_CL0SE, &error) 

where f 1 is the value returned by OpenTcp( ). Note that it is necessary to release both the readable and 
writcablc instances to cause the connection to be deallocated. Releasing the writeable instance closes the 
caller's end of the connection. Data can still be read from the readable instance until it is released, or other 
end closes (resulting in an END.OF.FILK indication). 

The parameters local Port, forelgnPort, and forelgnHost specify the sockets on which the TCP 
connection is to be opened, active specifics whether the connection should be active (i.e., send a 
connection "syn" packet), or passive (i.e., listen for an incoming "syn" packet), precedence and 
security specify the precedence and security values to be used for the connection. Specifying zero for 
these parameters will cause appropriate default values to be used. 

If the open is unsuccessful, OpenTcp() returns null, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 

File *OpenIp(protocol , error) 

char protocol; SystemCode *error; 

Interact with the Internet server to create an IP network instance, and return a pointer to a File structure 
opened in block mode thatcan be used to write IP packets to the network. 

To obtain a second File structure that can be used to read IP packets, use the call 

f2 - 0penFne(F1leServer(fl), FHeld(fl) + 1, 

FREAD + FBL0CK_M0DE + FRELEASEJDNJILOSE, &error) 

where fl is the value returned by 0penlp(). Note that it is necessary to release both the readable and 
writcablc instances even if only one of them is used, 

The protocol specifics which value of the protocol field in the IP packet headers is of interest. The 
readable instance will only return packets with the requested protocol value, and the client program should 
only write packets with the specified protocol field to the writcablc instance, though this is not currently 
checked by the server. If protocol is /.cro, it specifics "promiscuous" mode, in which ail IP packets arc 
returned which arc not of protocol types that have been requested by another client, and packets of any 
protocol type may be written. 

If the open is unsuccessful, 0penlp() returns null, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 

File *OpenPup( socket, error) 

unsigned long socket; SystemCode *error; 

Interact with the Internet server to create a PUP network instance, and return a pointer to a File structure 
opened in block mode that can.. be used to write Pill's to the network. 

To obtain a second File structure that can be used to read PUPs, use the call 

f2 ■■ 0penF1le(FneServer(fl), F11eld(fl) + 1, 

FREAD + FBLOCKJMODE + FRELEASE_ON_CLOSE, &error) 

where f lis the value returned by OpenPup( ). Note that it is necessary to release both the readable and 
writcablc instances even if only one of them is used. 

The socket parameter specifics which value of the socket field in the PUP headers is of interest. The 
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readable instance will only return packets sent to the requested socket, and the client program should only 
write packets widi the specified source socket to the writcablc instance, though this is not currently checked 
by the server. If socket is zero, it specifies "promiscuous" mode, in which all PUPs arc remrned which are 
not to sockets that have been requested by another client, and packets with any source socket number may be 
written. 

If die open is unsuccessful, OpenPup( ) returns NULL, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 

1 6.3.6. Miscellaneous I/O Functions 



Instance-Id Fneld(fHe) 
File •file; 

Return the file instance identifier associated with the open file. This was cither generated as part of Open ( ) 
or specified as an argument tothcOpenFile() operation that opened the file. 

Processld F1leServer(f He) 

File *f1le; 
Return the file server identifier associated with the open file. This was ciUicr generated as part of Open ( ) or 
specified as an argument to the OpenF 1 1 e ( ) operation that opened the file. 

unsigned FHeType(fne) 
File •file; 

Return the file type, which indicates the operations that may be performed on the open file as well as die 
semanUcs of these operations. 

unsigned Interactlve(fHe) 

File •file; 
Return TRUK (non/.cro) if die file has the type attribute INTERACTIVE, else h'ALSK (zero). 

File *OpenStr(str, size, error) 

unsigned char *str; unsigned size; SystemCode *error; 

Make the specified string look like a file. The file is FIXED.LENGTH, with one block of size size, and die 
end of file set to die end of this block, str must point to an area at least size bytes in lengdi. A file opened 
by OpenStr ( ) is identified as such by its file server (as returned by F11 eServer ( )) being equal to 0. 

SystemCode RemoveFlle(pathname) 
char 'pathname; 

Remove (delete) the file specified by pathname. 

SystemCode SetBreakProcess(f He, breakprocess) 
File *f1le; Processld breakprocess; 

Sets die break process associated with die specified file (which must be INTERACTIVE) to breakprocess. 



V-SYSTGM 5.0 Rl-J-T-RFNCU MANUAL PROGRAM ENVIRONMENT 



MISCELLANEOUS I/O FUNCTIONS 91 

If a break occurs on the file after a break process has been set, the IOJ5REAK reply will be returned to any 
outstanding read requests, and the specified break process will be destroyed. 

SystemCode SetInstanceOwner(f lleserver , fUeld, owner) 
Processld fileserver, owner; Instanceld fUeid; 

Set the owner of the specified file instance to be owner. 



PMntFile(name, file) 

char •name; File *f He; 

Print the value of each field in the given File structure on the standard output, identifying the file by the 
name name. Useful in debugging servers and I/O routines. 



SystamCode Changed rectory(name) 
char *name; 

Change the current context for the calling process to be the context specified by name, and return a standard 
system reply code indicating OK if successful, else the reason for failure, name is interpreted in the 
(previous) current context. This function is identical to chdir( ), except that die latter returns to indicate 
success or -1 to indicate failure. 
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— 17 — 
Numeric and Mathematical Functions 



17.1. Numeric Functions 

Most of the functions in the numeric section of the library are not called directly in user programs; they are 
accessed by the C compiler as needed. The following functions are useful in user programs: 



unsigned abs(value) 
1nt value 

Integer absolute value. 



1nt rand() 

Random number generator. Generates pseudo-random numbers in the range from to 2 -1. This is a very 
poor generator, identical to the one provided in Berkeley Unix 4.1. 

srand(seed) " 

unsigned seed; 

Rcsccd the rand( ) random number generator. 

17.2. Mathematical Functions 

The math-rclatcd functions in the V library arc listed below. They arc similar to die "section 3IVT functions 
of the Unix library. Sec the Unix manual for documentation. 



sin()- 


cos() 


tan{) 


asin( ) 


acos( ) 


atan( ) 


atan2() 


sinh( ) 


cosh( ) 


tanh() 


J0() 


jl() 


jn() 


yo() 


yi() 


yn() 


hypot() 


cabs() 


gamma( ) 


fabs() 


foot() 


ce1l() 


exp() 


log() 


loglO() 


pow() 


sqrt() 
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— 18 — 
Memory Management 



Blocks within a managed pool of memory can be dynamically allocated and freed within the address space 
of a team using the functions described below. Note that there is one pool of free storage for all processes in 
the team. Programmers must be careful to synchronize the processes allocating and freeing this storage. 
These routines provide essentially the same functionality as the standard C library. The memory allocation 
routines arc provided on a per-team basis. 



char *malloc(s1ze) 
unsigned size; 

Returns a pointer to a memory block that is size bytes long. NULL is returned if there is not enough 
memory available. 



free(ptr) 

chap *ptpj 
The memory pointed to is returned to the free storage pool. ptP must point to a block allocated by one of the 
routines listed, here. ■ •' ■ 



chap *pealloc(ptP, size) 

chap *ptp; unsigned size; 

Changes the size of die block pointed to by ptP to be size bytes. Returns a possibly moved pointer. 

chap *calloc(elements, size) 

unsigned elements, size; .,, 

Equivalent to malloc( elements* size), excepr the area is cleared to zero. Provided for allocating arrays, 

■ • • I 

cfree(ptp, elements, size) 

chap *ptp; unsigned elements, size; "' 

Frees storage allocated by cal loc( ). Actually, this function is identical to f pee(ptp), which may be usc< 
instead, elements and size arc ignored. 

:• I ""J I t 

unsigned Copy(dest1nat1on, source, count) 

chap *dest1 nation, •soupce; unsigned count; 

A block transfer function. Transfers count bytes from soupce to destl nation. Returns count. 

' '• 

unsigned blt(dest1nat1on, source, count) 

chap *dest1nat1on, *souPce; unsigned count; 
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Identical to Copy (). 

char *Zero(ptr, n) 

char *ptp; unsigned n; 

Zero memory. Writes n bytes of zeros starting at ptr, and returns ptr. 



clear(ptr, n) 

char *ptr; unsigned n; 

Clear memory. Writes n bytes of zeros starting at ptr. 

swab(pfrom, pto, n) 

char *pfpom, •pto; unsigned n; 
Swap the bytes in n 16-bit words starting at the location pf pom into a block starting at the location pto. 

The following functions arc of interest only to those managing memory (using the kernel primitives) in 
addition to that provided by the above routines. The current implementation of malloc( ) prevents these 
routines from adding space below the current top of die pool. 

<a1veToMalloc(stapt, length) 

char *stapt; 1nt length; 
Add the length bytes of memory at stapt to the pool used by the allocators described above, returning the 
number of bytes actually installed after alignment and error-checking is done. 

chap * GetMopeMallocSpace(m1n f actual) 

1nt min, *actual ; 
Malloc() calls this function to acquire more space for its pool; a default version is supplied, which is 
replaced if the programmer supplies a routine of this name. GetMopeMallocSpace( ) should return a 
pointer to at least ml n bytes of space and set 'actual to the number of bytes made available; MULL may be 
returned if no more space is to be added to the pool. 

In the default version, free memory is determined and extended based on the memory map and memory 
usage of the team (using die V kernel operations GetTeamS1ze( ) and SetTeamS1ze( )). 



V-SYSTEM 5.0 REFERENCE MANUAL PROGRAM ENVIRONMENT 



PROCESSES AND INTERPROCESS COMMUNICATION * 



— 19 — 
Processes and Interprocess Communication 



The process-related functions in the V C library provide services and/or interfaces between processes and 
the V kernel. They have no direct analog in the standard Unix C library. 

19.1. Kernel Operations 

These functions provide a convenient interface to kernel-provided services. Some of the functions execute 
kernel trap instructions, while others send messages to a pseudo-process inside the kernel.. 

A kernel operation executes as a single indivisible function call as far as the C programmer is concerned. 
Each kernel operation takes zero or more arguments and returns a single value. 

In the descriptions below, the active process or invoking process always refers to the process that executed 
the kernel operation. 

Some operations such as SctTcamPriority and SetTimc are intended to be used only by "operating system" 
or management processes and should not be used by application programs. 

1nt Awa1tingR8p1y(frompid, awaltingpid) 

Procassld frompid, wa1t1ngp1d; 
Return true (nonzero) if awaltingpid is awaiting reply from frompid; otherwise return false. Note: if 
awaltingpid is send blocked on frompid, but frompid has not yet received the message, this function 
will return false. 



Processld Creatoir(pid) 

Procassld pid; 
Return the process id of the process that created pid. If p1d is zero, return the creator of the invoking 
process. If p i d docs not exist or is the root process of the initial team, return 0. 

Procassld CreataProc8Ss(pr1ority, 1n1t1a1pc, 1n1tialsp) 
short priority; char *1n1t1alpc, •1n1t1a1sp; 

Create a new process with die specified priority, initial program counter and initial stack pointer and return its 
unique process identifier. 

The priority must be between and 127 inclusive, with the highest priority. 1 n 1 1 1 al pc is die address of 
the first instruction of the process to be executed outside of the kernel. Generally, 1n1t1alsp specifics the 
initialization of the stack and general registers and is processor-specific. In the case of the Motorola 68000, 
1 n 1 1 i al sp is a simple long word value that is assigned to the user stack pointer. 

The process is created awaiting reply from the invoking process and in the same team space. The segment 
access is set up to provide read and write access to the entire team space of the newly created process. The 
creator must reply to the- newly created process before it can execute. If there are no resources to create the 
process or the priority is illegal, a pid of is returned. 
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Usually programmers will prefer the Create ( ) call described later in this chapter. 

Processld CreateTeam(prlbr1ty, initialpc, 1n1t1alsp) 

short priority; char *1n1t1alpc, *1n1t1alsp; 
Create a new team with initial or root process having the specified priority, initial program counter, and initial 
stack pointer. 

CreateTeam( ) is similar to CreateProcess( ) except the new process is created on a new team. The 
new team initially has a null team space. It is intended that the creator of the team will initialize the team 
address space and root process state using SetTeamS1ze( ), MoveTo( ), and Wr1 teProcessState( ). 

CreateTeam returns if there are no resources to create the team or the root- process, or the priority is 
illegal. 

Delay(seconds, clicks) 

unsigned seconds, clicks; 
Suspend the execution of the invoking process for the specified number of seconds and clicks (where a click is 
a machine-specific unit, usually one clock interrupt). 

Del ay ( ) returns after the time period has passed, or the number of clicks remaining in the delay time if 
the process has been unblocked by Wakeup( ). A clock interrupt on the SUN workstation is 10 milliseconds. 

SystemCode DestroyProcess(pld) 
Processld p1d; 

Destroy the specified process and all processes that it created. When a process is destroyed, it stops executing 
its pid becomes invalid, and all processes blocked on it become unblocked (eventually). 

DestroyProcess( ) returns OK if p1d if successful, else a reply code indicating the reason for failure. 
DestroyProcess(O) is suicide. 

Usually programmers will prefer the Destroy( ) call described later in this chapter. 

Processld Foni»ard(nisg, frompld, topld) 

Message msg; Processld frompld, topld; 
Forward the message pointed to by msg to the process specified by topld as though it had been sent by the 
process frompld. 

The process specified by frompld must be awaiting reply from the invoking process. The effect of this 
operation is the same as if frompld had sent directly to topld, except that the invoking process is noted as 
the forwarder of the message. Note that Forward( ) docs not block. 

Forward() returns topld if it was successful, if unsuccessful. If topld is invalid, frompld is 
unblocked with an indication that its Send ( ) failed. 

Processld Forwarder(pld) 
Processld p1d; 



12 Proccsscs blocked on a nonexistent processes arc detected and unblocked by the clock interrupt routine checking periodically. 
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Return the process id that forwarded the last message received from p 1 d, providing pi d is still awaiting reply 
from the invoking process. If the message was not forwarded, p1 d is returned. If p 1 d does not exist or is not 
awaiting reply from the invoking process, is returned. 

Processld GetPid(1ogicalid, scope) 

1nt logical-id, scop©; 
Return the pid of the process registered using SetPi d( ) with the specified logi cal i d and scope, or if 
not set 

The scope is one of: 
LOCAL.PID Return a locally registered process only. 
REMOTE..PID Return a remotely registered process only. 
ANY.PID . Return a local or remote process pid. 

If logical 1 d is ACTIVE..PROCESS, the pid of the invoking proccssis returned. If a scope of remote is 
specified, the kernel broadcasts a request for a process identifier registered as this logical id to other 
workstations running the V kernel on the network. If the scope is any, the kernel first looks for a locally 
registered process; if one is not found, it then looks for a remote process. In this way, a kernel can discover 
the process identifiers of the standard server processes from odicr kernels, or at least from the kernel that is 
running the server process of interest 

Processld GetTeamRoot(pid) 

Processld pid; 
Return the process identifier of the root process of the team containing pid, or zero if pid is not a valid 
process identifier. A p1 d of zero specifics the invoking process. 

char *GetTeamS1ze(p1d) 

Processld pid; 
Return the first unused location in the team space associated with pi d, as set by SetTeamS i ze ( ) . If p i d is 
zero, die size of the invoking process's team is returned. If pi d docs not exist is returned. 

unsigned GetTime(clicksptP) 
unsigned *click.sptr; 

Return the current time in seconds. The standard is to represent time as seconds since January 1, 1970 GMT. 
If cl i cksptr is not null, the number of clock interrupts since the last second is stored at that location. 

SystemCode MoveFrom(spcp1d, dest, sre, count). 

Processld spcpld; chap •dest, *spc; unsigned count; 
Copy count bytes from the memory segment starting at spc in the' team space of s rep id to the segment 
starting at dest in the invoking process's space, and return the standard system reply code OK. 

The SPCpl d process must be awaiting reply from the invoking process and must have provided read access 
to the segment of memory in its space using the message format conventions described for Send(). 
MoveFrom( ) returns a standard system reply code indicating the reason for failure if any of these conditions 
arc violated. 
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SystemCode Mov8To(destp1d, dest, src, count) 

Processld destpid; char *dest, *src; unsigned count; 

Copy count bytes from the segment starting at sre in the invoking process's team space to the segment 
starting at dest in the team space of the destpid process, and return die standard system reply code OK. 

The destpid process must be awaiting reply from the invoking process and must have provided write 
access to the segment of memory in its space using the message format conventions described under Send( ). 
MoveTo( ) returns a standard system reply code indicating the reason for failure if any of these conditions arc 



violated. 



QueryKernel(p1d, groupSelect, reply) 

Processld p1d; 1nt groupSelect; Message reply; 
Query the kernel on the host where process p1d is resident A p1d of zero specifics the invoking process's 
kernel. x 

The groupSel ect field specifies what information is to be returned in the reply message. The available 
group selection codes arc MACHINH-CONFIG, to return information about the processor configuration, 
PKRIPHHRAl.-CONHG, to return a list of peripherals available on die machine, KKRNKL-CONHG, to 
return the kernel's configuration parameters, MKMORY- STATS, to return memory usage statistics, and 
KKRNI-L-STATS, to return other kernel statistics. These codes, and the corresponding structures Uiat may 
be returned, arc defined in the standard header file < Vquerykcrncl.hX 

Processld QueryProcessState(p1d, pb) 
Processld pid; ProcessBlock *pb; 
Copy the suite of the process into the structure pointed to by pb. The various fields in the structure arc 
defined in <Vproccss.h>, Their meanings should be self-explanatory. 

The message buffer is only available if p1d is the invoking process or is awaiting reply from the invoking 
process. If not, the appropriate fields in the structure arc zeroed. 

If p1d is zero, the process suite of the invoking process is returned. If p1d docs not exist, is returned; 
otherwise, p 1 d is returned. 

Processld ReadProcessState(p1d, state) 

Processld p1d; Processor_state *state; 
Copy the machine-specific processor state into the structure pointed to by state. The information returned 
is a subset of that returned by QueryProcessState(). 

If pid is zero, the processor suite of the invoking process is returned. If p1 d docs not exist, is returned; 
otherwise, p1d is returned. 

Processld Recelve(msg) 
Message msg; 

Suspend the invoking process until a message is available from a sending process, returning the pid of tliis 
process, and placing the message in the array pointed to by msg. 

Processld Rece1veW1thSegment(msg, segbuf, segslze) 
Message msg; char *segbuf; unsigned *segs1ze; 
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Suspend the invoking process until a message is available from a sending process, returning die pid of this 
process, and placing the message in the array pointed to by msg and at most die first •segsize bytes of the 
segment included with the message in die buffer starting at segbuf . The actual number of bytes in die 
portion of the segment received is returned in * s e g s i ze . 

Processld RecelveSpecif ic(msg, p1d) 
Message msg; Processld pid; 

Suspend die invoking process until a message is available from the specified process, returning the pid of this 
process, and placing the message in the array pointed to by msg. 

If pid is not a valid process identifier, RccciveSpecific returns 0. 

Processld Reply(msg, p1d) 

Message msg; Processld p1d; 

Send the specified reply message to the process specified by pid and return pid. 

The specified process must be awaiting reply from the invoking process. Zero is returned if the process 
docs not exist or is not awaiting reply. 

Rep1yWithSegment(msg, pid, sre, dest, bytes) 

Message msg; Processld pid; char *src, *dest; unsigned bytes; 

Send the specified reply message and segment to the process specified by p i d and return pid. 

The specified process must be awaiting reply from the invoking process. Zero is returned if the process 
docs not exist or is not awaiting reply. The segment size is currently limited to 1024 bytes. A 
ReplyWi thSegment( ) with a nonzero segment size may only be used to reply to an idempotent request 
(sccSend()). 

RereadMsg(msg, pid) 

Message msg; Processld pid; 

Reread into msg the message received from the process specified by pid, providing it is still ;iwailing reply 
from the invoking process. 

RereadMsg() copies the contents of Uic message buffer hist received from p1d into die array msg, 
providing die process specified by pid still exists and has not been replied to. If pid is zero, it is taken to 
mean die invoking process and rereads the last reply message. This operation also allows a newly created 
process to read the initial reply message from its creator. 



int SameTeam(pidl, p1d2) 
Processld pidl, pid2; 

Return true (nonzero) if Uic processes specified both exist and arc on the same team; otherwise return false. 
If eidicr pid is zero, the invoking process is assumed. 



Processld Send(msg, pid) 

Message msg; Processld pid; 

Send die message in msg to die specified process, blocking the invoking process until the message is both 
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received and replied to. The array specified by msg is assumed to be 8 long words. The reply message 
overwrites the original message in the array. 

If Send ( ) completes successfully, it returns the pid of the process that replied to the message. The pid 
returned will differ from diat specified in the call if the message is forwarded by the receiver to another 
process that in turn replies to it. If the send fails (for instance, because the intended receiver docs not exist), 
Send( ) returns the pid of die process the message was last forwarded to (the pid it was sent to, if it was never 
forwarded). The kernel indicates the reason for the failure by overwriting the first 16 bits of the message with 
a standard system reply code. (This places it in die replycode field for reply messages that follow the standard 
system format.) 

All messages must follow the kernel message format conventions as follows. The first 16 bits of the message 
arc considered to be a request code or reply code. The highest order 6 bits are assigned special meanings. 

Bit is if a request message is being sent, or 1 if a reply message. 

Bit 1 is 1 if the request code or reply code is considered a standard system code. Applications 

can use special request codes and reply codes internal to their programs but use standard 
ones for interfacing to other programs and the system. The remaining 4 bits arc 
interpreted with the following special meanings only if the message is a request. 

Bit 2 is 1 if die request is considered to be idempotent. This is just a hint to discriminate 

between requests diat do not need duplicate suppression and diosc diat do. 

Bit 3 is 1 if the request specifics a segment If 1, the kernel interprets the last 2 words of the 

message as specifying a pointer to die start of the segment and the size in bytes of die 
segment, respectively. The kernel dicn makes the segment available to the receiving 
process using MovcTo and MovcFrom. Access to the segment is controlled by the 
following two bits, which only have meaning if bit 3 is 1. 

Bit 4 • is 1 if read access is provided to die segment 

Bit 5 ' is I if write access is provided to the segment 

It is intended and assumed that most requests can be assigned a request code diat is stored in the first 16 bits 
of die request message, so that the bits arc set correctly for die request by die value of die request code. 

SetPid(log1cal1d, p1d, scope) 

1nt loglcalld, scope; Processld pid; 

Associate p1d with die specified logical id within the specifed scope. Subsequent calls to GetPid( ) with 
this logical 1d and scope return diis pid. This provides an efficient low-level naming service. 

The scope is one of: 
LOCAL.Pl ID Register the process in the local scope only. 
RKMOTFJ'ID Register die process in the remote scope only. 
AN Y_PID Register die process in both die local and remote scopes. 

The local scope is intended for servers serving only the local workstation. The remote scope is for network- 
accessed server processes serving several workstations (but not the local workstation). 'Hie any scope permits 
both local and remote access. 



SetTeamPr1or1ty(p1d, priority) 

Processld pid; short priority;- 
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Set the team priority of the team associated with p1d to the specified priority and return the previous team 
priority. 

Each process effectively runs with the absolute scheduling priority of its team's priority plus the priority 
specified when the process was created. SetT3amPriority( ) changes the absolute scheduling priority of 
each process on the team by modifying die team priority. This operation is intended for implementing 
macro-level scheduling and may eventually be restricted in use to the first team. 

If pi d is zero, the invoking process's team priority is set 

char *SetTeamSize(pid, addr) 

Processld pid; char *addr; 
Sets the first unused address for the team containing pid to addr. The new team size may be cither greater 
or smaller than the previous size. The new team size is returned; diis will normally be equal to addr. If there 
was not enough memory available to grant the request, the return value will be less than addr: if addr was 
below the starting address for team spaces on the host machine, the team space will be set to null and its 
starting address will be returned. Thus SetTeamSize(pid, 0) is a machine-independent way of setting a 
team space to null. 

A pid of specifics die invoking process. Only- die creator of die team or members of the team may change 
the team size and (consequently) the specified process must be local. 



SetTime(seconds, clicks) 

unsigned seconds, clicks; 

Set the kernel-maintained time to diat specified by seconds and cl i cks. 

The standard 'time representation used is the number of seconds since January 1, 1970 GMT, plus die 
number of clock interrupts since the last second. 



Processld Wakeup(pid) 
Processld pid; 

Unblock die specified process if it is delaying using Del ay ( ) and return pid. If the process does not exist or 
is not delaying, return 0. 



int ValidPid(pid) 
Processld pid; 

Return true (nonzero) if pid is a valid process identifier, otherwise return false. 

Processld WriteProcessState(pid, state) 

Processld pid; Processor_state *state; 

Copy the specified process state record into die kernel suite of the process specified by p1d and return pid. 

The specified process must be the invoking process, or awaiting reply from die invoking process. 
Wri teProcessState( ) returns if the process docs not exist, is not awaiting reply or there is a problem 
with the state record. The kernel checks that die new suite cannot compromise die integrity or security of the 
kernel. 

A pid of specifics the invoking process. A process that writes its own processor suite affects only the 
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machine- independent per-process area information kept as part of the state record (sec section 14.5). 

19.2. Other Functions 

Processld Create(pr1or1ty, function, stackslze) 

short priority; char *funct1on; unsigned stackslze 
Create a new process executing the specified function with the specified priority and stack size. The new 
process is blocked, waiting for a reply from the creator. The function Ready ( ) should be used to start die 
process running. The new process is on the same team as its creator, and inherits die creator's standard input, 
output, and error files, and die creator's current context (current working directory). 

Create returns the pid of the new process, or zero if a process could not be created. This iimction is 
usually preferable to calling the kernel operation CreateProcess( ) directly. 

Processld Ready(pid, nargs, al, .... an) 

Processld p1d; unsigned nargs; Unspec al, .... an; 

Set up the stack of the specified process and reply to it, Uuis placing it on the ready queue. The values al , 
...» an appear as arguments to the root function of the new process, while nargs is the number of 
arguments passed. Zero is returned if there is a problem, else p1 d is returned. 



Destroy(pld) 

Processld. p1d; 

Destroy the specified process. If the destroyed process was on the same team as the invoking process, the 
memory allocated to its stack by Create ( ) is freed. Warning: Do not invoke Destroy ( ) on a process that 
was not created by Create(); uscDestroyProcess() in that case. 



Su1c1de() 

Destroy the invoking process and free its stack. Su1c1de() is identical to Destroy(O), and the same 
warning applies. 

ex1t() 

Terminate the execution of the team (i.e., program), after closing all open files. Using the V executive, control 
is returned to the command interpreter. In bare kernel mode, control is returned to die l»ROM monitor. 



abort () 

Abort execution of the team by causing an exception in the calling process. 
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Naming 



The naming section of the library includes a number of functions that provide a convenient interface to 
V-Systcm naming protocol messages. Functions for creating and terminating storage server sessions are also 
included. 



SystemCode AddContextName(name, serverpid, contextid) 

char *name; Processld serverpid;; Contextid contextid; 

Add name as a local name for the context specified by (serverpid, contextid), and return OK, or a 
standard system reply code if an error occurred. This function creates and sends an 
ADD_CONTKXTJS A M K request message to the context prefix server. 

SystemCode AddLog1calName(name, loglcalpld) 

char *name; Processld loglcalpld; 
Add name as a local name for the default context specified by loglcalpld, and return OK, or a standard 
system reply code if an error occurred. This function creates and sends an ADD_CONTKXT_NAMB request 
message to the context prefix server. 

SystemCode AliasContextName(newname, oldname) 

char *hewnamei, *oldname; 
IDcfinc newname as a local name for the context specified by oldname. oldname is interpreted in the 
current context. Returns OK if the name was defined successfully, or a standard system code indicating the 
reason for failure. 

SystemCode Creat@Sess1on(host, user, password, sesslonname, owner) 
char *host, *user, *password, *sess1onname; 
Processld owner; 

Create, a session on the storage server (usually a Unix server) specified by host, using the given user name 
and password, and define sessionname as a local name for the user's home directory on this session. If 
owner is nonzero, the session owner is set to be the specified process; otherwise, the invoking process 
becomes the session owner. A session is automatically terminated when its owner no longer exists. 

The given session name is considered the primary name for the session (the SHSSION bit is set in its 
descriptor), and its definition should not be removed until die session is terminated. 

CreateSess1on( ) returns OK if successful, else a standard system code indicating the reason for failure. 

SystemCode Del et«ContextName( name) 
char *name; 

Remove the definition of the context name name, but do not delete the context it refers to. Return OK if 
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successful, else a system reply code indicating the reason for failure. 

The name is interpreted directly by the. context prefix server, not in the current context, since the function is 
ordinarily used only to remove names from the context prefix server's directory. 

Processld D1rectToCurrentContext( request) 

NameRequest *request; 
Direct a request to the current context, or to the context prefix server if the name begins with a square bracket 
('['). The function returns the pid to which the request should be sent, and puts the proper context id into the 
NameRequest message. This routine is provided to avoid duplicating the code that implements the square 
bracket convention in a large number of functions, request may be of any request type that fits the 
standard NameRequest template given in <Vnaming.h>. 

SystemCode GetContextId(name. serverpld, contextid) 

char •name; Processld *serverp1d; Contextid •contextid; 

Interpret the given name in die current context, and return a corresponding (scrvcrpid, contextid) pair in the 
locations pointed to by serverpid and contextid. The function returns OK if successful, or a standard 
system error code if an error is detected, such as the given name specifying an object Unit is not a context. 

SystemCode GetContextName(name, namelen, serverpld, contextid, nameserver) 
char name[]; unsigned *namelen; 
Processld •serverpld; Contextid •contextid; 
Processld nameserver; 

Perform an inverse mapping from the specified (scrvcrpid, contextid) pair to a character string context name. 
Hie request is sent to the server specified by nameserver. The array name must be *namelen characters 
in length; •namelen is modified to contain die actual length of the name upon return, •serverpid and 
•contextid arc modified upon return to indicate the context in which the name is valid. 
GetContextName( ) returns OK if the mapping was successful, or a standard system error code if a failure 
occurred. 

SystemCode GetF1leName(name, namelen, serverpid, contextid, 1nstance1d) 
char name[]; unsigned *namelen; 
Processld *serverp1d; Contextid *context1d; 
Instanceld 1nstance1d; 

Perform an inverse mapping from the specified (scrvcrpid, instanccid) pair to a character string file name. 
The array name must be * namelen characters in length; *namelen is modified to contain the actual length 
of the name upon return, •serverpid and *context1d arc modified upon return to indicate the context 
in which the name is valid. GetContextName( ) returns OK if the mapping was successful, or a standard 
system error code if a failure occurred. 

SystemCode Term1nateSess1on(sess1onname) 
char *sess1onname; 

Terminate the session specified by sesslonname and invalidate die name. Return OK on success, else a 
standard system code indicating the reason for failure. The session name is interpreted by the local context 
prefix server. The function checks that the SESSION bit is set in the name's descriptor; if it is not, 
NONI'XISTHNT.SHSSION is returned. 
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Program Execution Functions 



This chapter describes a number of functions relating to program execution. Most of these functions are 
used internally in the V executive; some of them may also be userul in user-level programs that need to start 
up other programs as part of their operation. All the functions in this chapter arc subject to change. 

21 .1 . Program Execution 

Processld LoadProg(argv, concurrent, teamServer, rtMsg, drtMsg, error) 
char *argv[]; int concurrent; Processld teamServer; 
RootMessage *rtMsg f *drtMsg; SystemCode *error; 

LoadProg() interacts with the team server to create a new team and load a program image into the new 
team space. It includes path searching code, which currently always looks for die program along die default 
path of 

1. The current context 

2. The context "[bin]" 

3. The context "[public]" 

If all these fail, LoadProg( ) loads the /execute program, which, when started, will attempt to execute die 
program on the storage server diat is providing the current context. 

The array argv contains pointers to die character string arguments to be passed to the new team. By 
convention, argv[0] should point to the name of the program. The last clement of die array must be a null 
pointer. The concurrent argument specifics whether die team is to be "owned" by die process executing 
the LoadProg( ) call (if concurrent is zero) or by the team server itself (if it is nonzero). The team server 
destroys any team whose owner ceases to exist: thus, programs to be run "in the background" should be 
(lagged as concurrent. The teamServer argument specifics which team server is to create the team. This is 
useful for running programs remotely. If teamServer is zero, die program is run locally. 

The rtMsg argument holds the root message to be passed to die new team. This message specifies Hie 
instances to be used for standard input, output, and error, die initial current context, and some other 
information. The fields in the message arc described in section 14.4. The drtMsg argument is the root 
message to be used to start up the postmortem debugger if a process team on die new team incurs an 
exception. The debugger root message should specify a real keyboard and display as standard input and 
output, even if the standard i/o for the program being loaded is redirected. These root messages arc stored by 
the team server. 

The function returns the process id of the new team's root process, or in case of an error. A standard 
system code is returned in the location pointed to by error. The new team can be started running by 
replying to the pid returned, using the same root message as was passed to LoadProg. 

Processld ExecProg(argv, concurrent, teamServer, rtMsg, drtMsg, error) 
char *argv[]; 1nt concurrent; Processld teamServer; 
RootMessage *rtMsg, *drtMsg; SystemCode *error; 
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ExecProg( ) interacts with the team server to create a new team and load a program image into the new 
team space, as in LoadProg( ). It then starts the new team running by replying to it. The arguments to 
ExecProg( ) are exactly the same as those to LoadProg( ). 

Processld RunProgram(argv, concurrent, teamServer, error) 

char «argv[]; int concurrent; Processld teamServer; 

RootMessage *rtMsg, *drtMsg; SystemCode *error; 
RunProgram( ) performs the same function as ExecProg( ) except that it uses the standard I/O bindings 
to initialize the rtMsg and drtMsg parameters that arc passed in to ExecProg( ). 

Processld LoadNewTeam( teamServer, name, concurrent, argv, 

rtMsg, drtMsg. error) p _ 

Processld teamServer; char *name; 1nt concurrent; char •argvrj. 

RootMessage -rtMsg, 'drtMsg; SystemCode *error; 
LoadNewTeamf ) is an internal routine called by LoadProg( ). It docs no path searching; the name of the 
file to load the program image from is given by the name argument. The other six arguments arc as described 
above, under LoadProg( ), though they appear in a different order. 

LoadNewTeam( ) calls Val 1 dProgram( ) to check whether the specified file appears to contain a valid 
program image, interacts with the team server to create the new team, and sets up the arguments on the new 
team's stack. 

Processld LoadTeam( filename, priority, stackslze, error) 

char 'filename; short priority; 

1nt stackslze; SystemCode *error; 
Create a new team with die specified root process priority, and load the program contained in the specified 
file into it. The number of bytes specified by stacks 1 ze is allocated at the end of die team space as a stack 
area for the team root process unless stackslze is -1, in which case the default 4000 bytes arc allocated, f 
the operation is successful, the pid of the new team's root process is returned; otherwise is returned. It 
error is not num., a standard system reply code is returned in the location to which it points. 

This function docs not request the team server to create and load the team; it creates the team and performs 
the team load itself. It is normally preferable to use one of the other functions described above, all of which 
make use of the team server. 

SystemCode RemoteExecute(processF1le, programname, argv, mode) 
File *processFne[2]; char *programname; 
char *argv[]; unsigned short mode; 

Cause the specified program to be executed on the server machine providing the invoking process's current 
context by opening a file in FliXFCUTH mode. This function is used by the /execute program. 

The argv parameter is an array of null-terminated strings which arc to passed as arguments to the program. 
The array itself is terminated by a null pointer, mode should be FRKAI) or FCREATB. A File structure 
describing a stream from which the program's standard output can be read is returned in processF11e[0]. 
If the mode is FCRKATF, a File structure describing a writcabic stream that is fed into the programs 
standard input is returned in processFHeCl]. RemoteExecute() returns OK if succcsslul, else a 
standard system code describing die error condition. 

Closing die writcabic file passes an end-of-file indication on to die remote program; Closing die readable 
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file terminates the program. 
21 .2. Other Functions 



File *Va11dProgram(fnename, error) 

char *f11ename; SystemCode *error; 
This function opens the file specified by filename and checks whether it has a valid "magic number," 
marking it as an executable V program image. If it is a valid program, Val idProgram( ) returns a pointer 
to a File structure describing the open flic; if not, it closes the file again and returns NULL-. A standard system 
code is returned in the location pointed to by error. 'Hie error code KND_0F_F1LE indicates that the file 
was too short to be a valid program, while 3AD_STATE indicates that the magic number was invalid. 



SetUpArguments(pid, argv) 

Processld pid; char *argv[]; 

SetUpArgumentsO is the function called by LoadProg() to set up the arguments on a newly created 
team's stack. Users will not nonnalty need to call it directly. The array argv has the format described under 
LoadProg( ), above. The process id pid specifics the root process of the team whose arguments arc to be 
set up. 

ParseLine(start, argv, maxArgs) 

char 'start; char *argv[]; int maxArgs; 

ParseL1ne( ) parses a command line into separate words, null terminating each one, and filling in an array 
of pointers to each word. Spaces and tabs are recognized as word separators. This routine is used by the V 
executive to construct an argv array to pass to LoadProg( ). 

The start argument points to the command line, which should be a null-terminated character string. The 
string is modified by inserting null characters after each word. The array of pointers created is returned in 
argv, which should be defined in the calling program to be of size maxArgs. ParseU ne( ) terminates the 
array with a null pointer. If there are too many words in the command line to fit in the array, only the 
leftmost maxArgs - I words arc returned. 
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Control of Executives 



Instances of the V executive, or command interpreter, arc normally created and controlled directly by the 
user interacting with the sytstcm. However, this control is also available to programs through the following 
functions: 

1nt CpeateExec(execsepvep, inserver, Infile, outserver, outfile, 

errserver, eppfile, namesepvep, context, flags, execpld, 
error) 

ppocessld execsepvep; 

Ppocessld insepvep, outsepvep, erpsepvep; 

Instanceld infile, outfile, eppfile; 

Ppocessld namesepvep; 

Contextld context; 

shopt flags; 

Ppocessld *execpid; 

SystemCode *eppop; 

Create an instance of the executive with die specified standard input, standard output, standard error output, 
and context. Kach of the three standard i/o files is specified by two. parameters, the server pid and the 
instance identifier within that server. This means that all these instances must be opened before Create Kxec 
is called. Context is specified by two parameters, a name server pid and a context identifier within that 
namescrver. The GctContcxtld function will map a context name into such a pair. Kxccscncr is the pid of 
die exec server to which the request is being made. 'ITic Flags parameter determines which if any of the 
standard i/o instances are to be owned by the newly created executive; it may be any combination of 
RKLKASK- INPUT.RHI .HASH- OUTPUT, and RHLHASH- HRR. If for example RH1 .HASH- INPUT is 
specified, die executive will own its standard input instance and will release it on termination. 

CrcatcKxcc returns an exec indentifier, a small integer which will be used to refer to this executive in other 
executive control requests. In the location pointed to by cxecpid it returns die process id of the new executive. 
In the location pointed to by error it returns a system error code; if this code is not OK, the exec identifier and 
cxecpid arc meaningless., 

WARNING: a server process cannot call CreateKxec with a file instance pointing to that server itself, or the 
server and the cxccscrver will become deadlocked waiting for each other. A server that needs to do this 
should.crcatc a subproccss to call CrcatcKxcc. 



SystemCode DeleteExec(execsepvep, exocid) 
Ppocessld execserver; 
1nt exedd; 

Delete die executive specified by cxecid, along with the program running under it if any. It need not have 
been created by diis process; there is no concept of ownership of execs. Note Uiat Urn is not die only .way 
executives vanish; they also terminate on end of file on the standard input DcictcKxcc will return 
NOT- FOUND if cxecid is invalid. 
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System 

Inquire about the state of the specified exec. If successful, it returns a code of OK, and the following 
information: inexecpid die process id of die exec; in program, the process id of the program running under it, 
if any; in status, the status of the exec. Status can be one of 

EXEC - FREE Exec is waiting for a command. 

EXEC- LOADING 

exec is in the process of loading a program. 

EXEC- RUNNING ... 

A program is running under this exec. In this case and this case only, program returns 

relevant information. 

EXEC- HOLD Exec has been created but not yet started. Hopefully this state should never be observed, 
as it is taken care of within CrcatcExcc. 

SystemCode KmProgram(execserver f exedd) 
Processld execserver; 
int exedd; 

Kill the program, if any, running under the. specified exec. Returns OK is successful, NOT- FOUND if 
execid was invalid, NONEXISTENT- PROCESS if there was no program running under that exec. 



SystemCode CheckExecs(execserver) 
Processld execserver; 

Causes the execserver to do a check on ail executives. Any of them whose standard input server or standard 
output server (but NOT standard error server) has died is destroyed during .the check. This should be called 
after an action that might have destroyed an i/o server which was providing standard i/o for one or more 
executives. 



V-SYSTP.M 5.0 REFERENCE MANUAL PROGRAM ENVIRONMENT 



SERVICE REGISTRATION AND SELECTION FUNCTIONS 113 



— 23 — 
Service Registration and Selection Functions 



This chapter describes a number of functions which deal with the globally visible service server; which 
provides registration and selection facilities for globally visible services. A description of the service server 
and the details of how to interact with it are provided in its servers manual chapter. This chapter assumes that 
die reader is familiar with the servers manual chapter and bases the form of its explanations on that 
assumption. All the functions in this chapter arc subject to change. 

23.1. Registration Facilities 



Instanceld Rag1sterServer(nameType, namelndex, typelndex, 

ovmepPid, desc, descLen, error) 
1nt nameType; 
int namelndex; 
1nt typelndex; 
Ppocessld ownerPid; 
chap *desc; 
1nt descLen; 
SystemCode *error 

RegisterServer registers die server descriptor (actually any object descriptor) pointed to by desc with 
die service server. descLen indicates how long die descriptor is in bytes. The owner of the descriptor is 
specified by ownepPld. It is assumed that the descriptor contains both a valid server name and type field, 
whose starting indices within the descriptor are given by namelndex and typelndex. The type field is 
assumed to be a null-terminated string field. There arc two types of name field allowed: a process id or a 
null-terminated string field. nameType specifies which type of name field is being used. The allowable 
values for nameType arc defined in die Vsepvice.h include file, eppop is used to return a status value 
indicating whether the operation was successful or why it failed. If the operation is successful then 
ReglsterSePvep returns an id number for the server's registration entry. This is used for unrcgistering the 
server (and possibly other diings in the future). 



SystemCode UnpeglstepSepvep(sePvepId) 
Instanceld sepvepld; 

UnpeglstepSePvep removes a server's registration entry from the service server's database. It takes as 
argument the id number returned from die original RegisterServer operation. 

23.2. Selection Facilities 



Instanceld CreateSe1ect1onInstance(sepvepType, pattepn, pattepnFcn, 

howMany, desc, descLen, eppop) 
chap *sepvepType; 
chap 'pattern ; 
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1nt patternFcn; 

int howMany; 

char *desc; 

1nt descLen; 

SystemCode *error; 
CreateSelect1onInstance() specifics a set of registered objects to associate with a selection instance 
and returns the first entry of the instance in desc. descLen specifies the maximum size that the descriptor 
returned may be. If the selected descriptor is larger than that then only the first descLen bytes arc returned. 
The server type under which selection is to take place is specified by the serverType field, which is a 
null-terminated string. The pattern-matching function to be used is specified by patternFcn. Values that 
this parameter may assume arc defined in the Vservlce.h include file. The pattern to match against 
registered descriptor entries is pointed to by pattern. The format of the pattern as far as this function is 
concerned (its interpretation within the service server will depend on which pattern-matching function is 
specified) is a null-terminated string. howMany specifics whether one or more selections is desired. If only 
one selection is desired then that selection is returned in desc and no selection instance is created. I his 
provides a means of circumventing the overhead of establishing a full-blown connection for obtaining just 
one selection, error is used to return the status of the operation performed. If the operation is successful 
then CreateSelectionlnstance returns an instance id for the selection instance established. ('I his 
value is meaningless if howMany equals 1.) 
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Graphics Functions 



The Virtual Graphics Terminal Service (VGTS) allows the display of structured graphical objects on a 
workstation running the V system. This chapter describes the interface of a client (application) program to 
the VGTS to provide facilities for the creation, destruction, and editing of structured display files (SDFs). 
The user interface to the VGTS is described in the View Manager chapter (chapter 3) of the Commands 
Manual. For simple text applications, the VGTS implements the standard I/O protocol. The functions in 
this chapter arc primarily for graphics applications. 

24.1. Terminology 

The central concept of the VGTS is that application programs should only have to deal with creating and 
maintaining abstract graphical objects. The details of viewing these objects arc taken care of by die VGTS. 
This is in contrast to traditional graphics. systems in which users perform the operations directly on the screen, 
or on an area of the screen referred to as a viewport or window. Thus die VGTS deals with declarative 
information radicr than procedural; you describe what the objects are rather than how to draw them. 

The following arc the types of objects managed by the VGTS: 

SDF A structured display file is a name space in which symbols and items arc defined. Each 

item can be given a unique identifier by the client. 

Item Items can be cither graphical primitives such as rectangles, lines, or text, or symbols, which 

consist of other items. 

Symbol A list of items (primitives or calls to other symbols) used to represent the hierarchical 

structure of the display file. 

VGT A virtual graphics terminal, can be eidicr an emulation of an ANSI standard text terminal, 

or a general graphics terminal which can display an instance of a symbol in some SDF. 

Event Graphical input is in terms of events in the coordinate space of some virtual graphics 

terminal. For example, a mouse click used to select a displayed object. 

View Both applications and users can create views of Virtual Graphics Terminals. A view 

consists of a viewport on some screen of some workstation, a window onto some VGT 
giving the world coordinates of the viewed area, and some other viewing parameters. The 
same VGT can appear in several different views, with independent control of all 
parameters. 

Items within an SDF arc named with 16 bit identifiers chosen by die application. It is assumed that the 
application will maintain some higher-level data structures, along with the appropriate mapping to these 
internal item names. Items that will never be referenced can be given item number zero. The item names arc 
global to each SDF, but applications may also have several SDFs for different name spaces. The item 
identifiers arc hashed into a symbol table, so there arc no constraints on dicir values. Item numbers can refer 
to both definitions of symbols and their instances. 

For example, a picture of a bicycle might define a symbol for a wheel. This definition of the wheel symbol 
is given item number 4. There may then be two instances of item number 4, Uiat arc given item numbers 5 
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and 6. The individual spokes of the wheel arc components of symbol number 4, but arc all given item 
number 0, since we will never want to refer to any of them. If it is desired to delete or move any individual 
spoke, then the items may be given numbers. 

Each item has the following parameters: 

Item A 16 bit unique (within the SDF) identifier for this object, or zero. This identifier is 

referenced by the client when performing editing operations. 

Type One of the predefined types described below, cither a primitive type or one to indicate 

structure. Currently eight bits arc allocated to this. 

TypcData Right bits of type-dependent information, like the stipple pattern number for a filled 

rectangle. Other attributes are stored here, such as the font index for general text. 

Xmin Minimum X coordinate of the bounding box. All coordinates are in "world" coordinates, 

stored as signed 16 bit signed integers. 

Xmax Maximum X coordinate of the bounding box. 

Ymin Minimum Y coordinate of the bounding box. 

Ymax Maximum Y coordinate of the bounding box. 

Pointer Depending on the type, this is cither a pointer to some data like an ASCI I text string, or for 

symbol calls, a pointer to the called symbol. 

Sibling All the component items in a symbol arc linked together via this chain. Normally it should 

not be visible to the client, unless the client wants to step through a symbol definition in 
order. 

24.2. SDF Primitive Types 

Some of the meanings of the fields depend on the type of the item. The following arc the types of items 
that occur in display records in a structured display file: 

SDF.FlLI.ED.RECrANGLE 

A filled rceuinglc. The TypcData field determines the stipple pattern, or color on the Iris 
system. Refer to the Vgts . h include file for the available colors. 

SDFJ-IORIZONTALJJNE 

Horizontal line from (Xmin,Ymin) to (Xmax,Ymin). Ymax is ignored. 

SDF.VKRTICAL_I.INE 

Vertical line from (Xmin,Ymin) to (Xmin, Ymax). Xmax is ignored. 

SDF_POINT A point, which usually appears as a 2 by 2 pixel square at (Xmi^Ymin); 

SDF_SIMPULTEXT 

A simple text string, which appears at (Xmin,Ymin) as its lower left corner. Currently only 
a single fixed-width font is available. ITic values of Xmax and Ymax need not surround 
the text, but they arc used as aids for redrawing, so should correspond roughly to the real 
bounding box. 

SDFJ3ENERALJJNE 

A generalized line, from (Xmin,Ymin) to (Xmax, Ymax). Note that Xmin etc. arc slightly 
misleading names. The SDF manager actually sorts the endpoints and calculates the 
bounding box correctly. 
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SDF_OUTLlNE Outline for a selected symbol. Xrnin, Xmax, Ymin and Ymax give the box for the outline. 
The TypcData field specifics bits to select each of the edges: LcftEdgc, RightEdgc, 
TopEdge or DottomEdge. 

SDF.HORIZONTAL.REF 

A horizontal reference line at (Ymin + Ymax)/2. Reference lines consist of a thick line 
with two tick marks at the ends, and some associated text. They arc intended for use in 
computer aided design applications like the Yale layout editor. 

SDF.VERTICAL.REF 

A vertical reference line at (Xmin + Xmax)/2. 

SDF_SEL_HORIZ_REF 

A thick (selected) horizontal reference line at (Ymin + Ymax)/2. 

SDF_SEL_VERT_REF 

A thick (selected) vertical reference line at (Xmin + Xmax)/2. 

SDF_TKXT A string of general text, with a lower left corner at (Xmin,Ymin). The TypcData field 

determines die font number, Xmax is recalculated from the width information for the 
font. Sec section 24.6 for an example. 

SDF_RASTER A general raster bit-map with a lower left corner at (Xmin,Ymin), and upper right corner at 
(Xmax,Ymax). The TypcData field determines if the raster is written with ones as black or 
white. The pointer field points to the actual biunap, in 16 bit-wide swaths. 

SDFJSPL1NE A spline object, of which a special case is a polygon. 'ITic pointer field points to a spline 
structure as defined in the include file <splincs.h>. 

'ITicrc arc a few other types that arc not visible to the user. For example, symbol definitions and calls are 
represented as items with most of the same attributes. 

Note: The following SDF item types arc not yet implemented for the SMI model 120 framebuffer: 
SDF2us()11{XM\SDF2us()RASMM-:R,SDh7us()Gl-NERAL-LlNKandSDl'2us()SPI.lNE. 

24.3. SDF Manipulation Procedures 

Hie following are the currently defined procedures used to manipulate the SDF. When culled from C, all 
return values except the actual C expression value arc passed via pointer parameters. If any pointer is NULL, 
no value is returned for that parameter. 

short CreateSDFQ 

Create a structured display file, and return it. Return -1 if the VGTS runs out of resources. This must be 
done before any symbols arc defined. 



short DeleteSDF(sdf) 
short sdf; 

Return all the items defined in the given SDF to free storage. This includes all strings, polygon structures, and 
spline structures associated with items in the SDF. Returns sdf. 



short Def 1neSymboT(sdf , Item, text) 
short sdf. Item; 
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char *text; 

Enter symbol into the symbol table, and open it for editing. The sdf is returned from a previous CrcatcSDF 
call. 'Hie text is an optional descriptive name for the symbol, used in the hit selection routines for 
disambiguating selections. Returns' 1 tern if successful, or zero on some error. 

short EndSymbo1(sdf , Item, vgt) 
short sdf, Item, vgt; 

Close the given symbol so no more insertions can be done, and cause the vox to be redrawn to reflect the new 
SDK Called at the end of a list of Addltem() and AddCal1() calls defining a symbol, started with 
Def IneSymbol ( ) or Ed1 tSymbol ( ). Returns item if successful. Note that the vgt number is only a 
"hint," because an object can exist in several different vgts. The client can alwaysxall Dlspl ayltem( ) to 
force a vgt to be redrawn. 

short Addltem(sdf , Item, xmin, xmax, ymin, ymax, 
typedata, type, string) 

short sdf, Item, xm1n, xmax, ymin, ymax; 

unsigned char type, typedata; char *string; 
Add an item to the currently open symbol. Returns the item name if successful, or zero on errors, string is 
an optional pointer to a text string used only for text types and reference lines, or special object descriptors for 
rasters and splines. The i tern number can be /.cro to indicate that the item will never be referenced. 

short AddCa"M(sdf, Item, xoffset, yoffset, calledSymbol ) 
short sdf, item, xoffset, yoffset, calledSymbol ; 

Add an instance of the called symbol to the currently open symbol. The called symbol instance is placed at 
(Xoffset, Yofftct). Returns Item if successful, otherwise. 

short Deleteltem(sdf , item) 

short sdf, Item; 
Delete an item from the currently open symbol definition. 'Hie item name will be removed from the hash 
table. Symbol calls can be deleted just like any other item, but symbol definitions are deleted by the 
DclcteSymbol function. Again, returns zero on errors, the item name if successful. 

short Inqu1reltem(sdf , Item, xmin, xmax, 

ymin, ymax, typedata, type, string) 

short sdf, item; short ♦xmin, •xmax, *ym1n, "ymax; 

unsigned char *type, 'typedata; char *str1ng; 
All parameters except sdf and item arc pointers, horcach non-null pointer, the value of the field for that 
item is returned. Zero is returned if the item could not be found; otherwise item is returned. 



short InquireCal1(sdf , Item) 
short sdf, Item; 

Return the item name of the symbol called by the indicated item. Returns zero if the item is not a call, or 
could not be found. 
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short Changeltem(sdf , Item, xmin, xmax, 

ymin, ymax, typedata, type, string) 
short sdf, Item, xmin, xmax, ymin, ymax; 
unsigned char type, typedata; char *string; 

Change the parameters of an already existing item. Return zero if the item did not exist, otherwise Item. 
This is equivalent to deleting an item and then reinserting it, so the item must be part of the open symbol. 

short Ed1tSymbo1(sdf , Item) 
short sdf, Item; 

Open an already existing symbol definition for modification. This has the effect of calling 
Def IneSymbol ( ) and inserting all the already existing entries to the definitions list The editing process is 
ended in the same way as the initial definition process - a call to EndSymbol ( ) . Returns 1 tern if successful, 
otherwise. 



short DeleteSymbo1(sdf , Item) 
short sdf, Item; 

IDclctc the definition of a symbol, item must be a symbol definition. Any dangling instances of this symbol 
will remain, but will contain nothing. Returns item if successful, else 0, 

To continue the example of the previous section, to create the bicycle figure we would use code like die 
following: 

short sdf; 

sdf • CreateSDF(); 

Def i neSymbo 1 ( sdff , 4 , "Wheel" ) ; 

Addltem( sdf , .xmin , xmax , ymin , ymax , ,S0F JSENERALJ.INE .NULL) ; ' 

(add the components of the wheel symbol) 

EndSymbol (sdf .4,0); ' 

Def ineSymbol( sdf, 3. "Bicycle-); 
AddCall(sdf ,5,xl.ymin,4); 
AddCal1(sdf .8, x2, ymin, 4); 
EndSymbol (sdf .4,0); 

24.4. VGTs and Views 

Once a client has defined some graphical objects, it also needs to provide information on which objects can 
be viewed. I'.vcry VGT (Virtual Graphics Terminal) is an item (usually a structured symbol) that is associated 
wilh one or more views* that actually appear on the screen, lurch vgt can exist in zero or more views, but 
each view has exactly one VGT associated with it. The "SDI ; Numbers" can be thought of as separate object 
definition spaces, while die vgts arc object instance spaces. Symbol definitions arc shared between vgts, but 
instances of symbols arc not 

The VGTS lets a user view objects in any vers anywhere on the screen in views. Rach view has a zoom 
factor, a window on the world coordinates of some VGT, and screen coordinates which determine its viewport. 
Although the client can create default views, die VGTS user can change diem with the window manager, and 
create and destroy more of them. Routines for the client's manipulation of vers and views: 

1nt CreateVGT(sdf , type, topltem, string) 
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short sdf; int type; short topltem; char *str1ng; 
Create a VGT, return the vgt number, and put the indicated item as the top-level item in the vgt. The type 
can be some combination of TIT, GRAPHICS, and ZOOMABLE. The Pads created by making TTY vgts 
can presently only be manipulated by the VGTS or through the I/O protocol interface (Sec the description of 
OpenPad in section 24.7.2). If the ZOOMABLE bit is set, the view zooming factor can be changed by die 
user. The topltem can be zero to indicate a blank vgt. Returns negative on errors. 



1nt DeleteVGT(vgt) 
short vgt; 

Destroy the given VGT. All the views of the vgt will also be destroyed. 

D1splayltem(sdf , topltem, vgt) 
short sdf, topltem; int vgt; 

Change the top-level item in a vgt. The new item is displayed in every view that contains the vgt. 

1nt Defau1tV1ew(vgt, width, height, wXmln, wYmln, 
zoom, showGMd, pWldth, pHelght) 

short vgt, width, height, wXmln, wYmln, zoom, showgrid; 

short *pW1dth, «pHeight; 
Create a view of the given vgt, with the user determining die position on the screen with the graphics input 
device. Hie width and height parameters give the initial size of the view if they arc positive. Zero (or 
negative) values indicate that the user should determine die size with die mouse at run-time. Sec the View 
Manager section of die commands manual (chapter 3) for more information about the user interface. 

If the pVMdth and pHelght pointers arc non-NUIX, then the shorts which they point to receive the 
selected width and height. wXmln and wYmln arc the world coordinates to map to die left and bottom edges 
of die viewport. The zoom factor is the power of two to multiply world coordinates to get screen coordinates. 
The zoom factor may be negative, to denote that a view is zoomed out. If showGMd is non-zero a grid of 
points every 16 pixels is displayed in die window. Returns negative on error. 

24.5. Graphical and Character Input 

'Hie VGTS maintains an event queue for each instance, and die vers associated with the given file instance. 
The mode bits of the instance give the kind of events diat will be queued. The following functions arc 
available to handle die event queues: 

LISTTYPE F1ndSelected0bject(sdf , x, y, vgt, searchType) 
short sdf, x, y, vgt; 
char searchType; 

Return a list of items that arc at or near die selected location within die VGT. Along with each item is a set of 
edges, to indicate that the hit was near one or more edges of the object. The searchType selects one of 
several modes of hit detection, as given in die <Vgts.h> include file. Usually the constant value AT 1 will be 
used. The return type LIS'lTYPE is also defined in this file. 
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typedef struct MinElement 

short item; 

short edgeset; 

struct MinElement *next; 
} MINREC, -MIMPTR; 

typedef struct Listlnfo 

{ 

MIMPTR Header; 

short MumOfElements; 

} LISTTYPE; 

short popup(menu) 

PopUpEntry menu[]; 
Provide a "Pop-Up" menu. The menu argument points to an array of PopUpEntry structures, each of which 
is a string and a code. The array is terminated by a NULL string. The code of the menu item selected by the 
user is returned. If the user clicks outside die menu a negative value is returned. 

typedef struct 

char *string; /* String to display. */ 

unsigned char menuNumber; /* Number returned if entry selected. */ 
} PopUpEntry; 

24.6. Defining and Using Fonts 

short Def 1neFont(name, fileName) 

char *name, "fileName; 
Defines a font to be used in subsequent SDI ; JJ'1 ; .XT items. The name is a pointer to a string giving the name 
of the font, for example, "HclvcticalOir. The font is read by the VGTS from the file with the pathname 
given as the second argument. The fileName argument can be null to indicate a read from the standard 
place. The fontlD returned by this call is used as the TypcData field of the Addltcm call for these characters. 
A negative return value indicates an error. For example, 

short roman - 0efineFont("TimesRomanl2'', NULL); 

Addltem(sdf, 0. x, x, y, y. roman, S0F_TEXT, -Hello") 
will display die string "Hello" in the Times Roman font at 12 point size, at the position (x,y) on the screen. 

24.7. Using the VGTS 

The constants for mouse search types, vcrr usage types, etc. are found in the include file Vgts . h. The stub 
routines arc available in the default V library, so just including the option -V on your cc68 command line for 
linking should work. Do NOT include the -1 Vgts option on your command line. 

Use -IVgts on your cc command line rbr transparently running programs on a Unix system. Use 
-I/usr/sun/lnclude to get the file Vgts . h. This package uses an escape sequence which can be used 
through PUP Telnet, IP Telnet, or with the remote command execution facility of the executive. Please 
contact the author for the details of this protocol if you wish to implement it on some other operating systems. 
There already arc efforts underway for using this protocol from TOPS-20 assembler programs (e.g. SUDS) 
and IntcrLisp. 
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24.7. 1 . Cooking You r Pads 

The following mode bits arc maintained for each pad to indicate the amount of rawness of the I/O: 

CRJnput Change the CR (return) character to LF (UNIX newlinc) on input. This is for the benefit of 

UNIX programs which expect '\n' as a line terminator. 

LF.Output Change LF to CR-LF on output. That is, every line-feed operation is preceded by a return. 

Echo Echo input characters. This bit should be off for programs which can also run on the kernel 

console device. 

LineBuffcr Wait for a line of input before returning. The user interface to die line editing feature is 

described in section 2.7.1. 

PagcOutput Block the writer each time a pad fills up with output, and wait for the user to issue a 

command which unblocks the pad. The user interface to the PagcOutput feature is 
described in section 3.3. This bit is "on" by default 

PagcOutputHnablc 

When turned on in a Modify Pad request, this bit causes the new value of die PagcOutput 
bit to be assigned to a user-controlled, "sticky" enable/disable bit. The PagcOutputHnablc 
bit should only be used by "privileged" programs (such as executives) as a means U> allow 
the user to "permanently" disable paged output mode. A QUKRY.KILK request will 
return the actual value of the PagcOutputHnablc bit. 

DiscardOutput When set, this bit causes all output to a pad to be ignored. It is automatically set when the 
user types 'q' to a pad that is blocked at the end of a page in PagcOutput mode. It is 
automatically cleared whenever the VGTS sends input to a program that is reading from 
the pad. The bit may also be cleared "manually" via ModifyPad. Application programs 
should call ModifyPad to clear this bit before sending a prompt to a pad, to insure that the 
prompt is not discarded along widi any previous output diat was discarded at die user's 
request 

Report Transition Report every change of buttons on the graphical input device as a significant event. 

ReportClick Report events only when all the buttons have been released on the graphical input device. 

NoCursor Do not display a cursor in the indicated pad. 

'Hie default when pads arc created, or commands arc initially run by the executive, is for all die keyboard bits 
to be on, and die mouse bits to be off. 

24.7.2. Other Interface Routines 

The following routines to communicate with the VGTS via die I/O protocol interface arc in die V library: 

File *OpenPad( name , lines , columns , error) 
char *name; 
short lines, columns; 
SystemCode *arror; 

Rcturnsa file descriptor for a new pad. error is a pointer to the reply code, normally OK. A null pointer is 
returned on an error. Note that die file descriptor returned is open for writing. If you want to read from it, 
you must use OpcnFilc to create another file descriptor with the same filcscrvcr and filcid. 
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SelectPad(file) 

File •file? 

Causes die indicated file to be selected for input, and brought to the top. 



Mod1fyPad( file, mode) 

File •file; 

1nt mode; 
Sets the Cooked mode of the file, mode is some combination of the bits described in the previous subsection. 



int QueryPad(flle) 

File *f1le; 
Returns the Cooked mode of the file, some combination of the bits described in the previous subsection. 



int QueryPadSize(file,plines,pcols) 

File •file; 

short *p1ines, *pcols; 
Gets the number of rows and columns of the specified pad, storing them in the shorts pointed to by pi 1 nes 
and pcols. The value returned is the same as for the preceding function. 

GetTTY() 

Puts the terminal in raw mode. The Unix version of this routine docs the appropriate UNIX operation if 
standard input is a tty device, otherwise it sends the proper code for the remote execution facility. 

ResetTTY() 

Restores the mode before die last GetTTY( ). Runs under UNIX as well, checking standard input properly. 

GetGraphicsEvent(file,px,py, pbuttons) 
File •file; 
short *px, *py, *pbuttons; 

Waits for a graphical event in the indicated vgt, and returns the world X and Y coordinates in the shorts 
pointed to by px and py. llie suite of the buttons is returned in the short pointed to by pbuttons. Use the 
file pointer stdln to get events in vers that were created with CreateVGT( ). 

SystemCode GetGraph 1 csStatus ( f i 1 e t px , py .pbuttons ) 
File •file; 
short *px, *py, *pbuttons; 

Returns after any motion die world X and Y coordinates in die shorts pointed to by px and py. The state of 
the buttons is returned in die short pointed to by pbuttons. The value returned will be BOF if die graphics 
cursor is not within a view of the given VGT. 



GetEvent ( f 1 1 e , px , py , pbuttons , cbuf ) 
File •file; 
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short *px, *py, *pbuttons; 
char *cbuf; 

Waits for any event in the indicated VGT, and returns the world X and Y coordinates in the shorts pointed to 
by px and py, and the buttons in the short pointed to by pbuttons if the event is graphical, or else returns 
the characters in the buffer pointed to by cbuf . The return value is zero for a graphical event and die byte 
count for keyboard events. 



RedrawPad(flle) 

Waits until the indicated pad. is redrawn. 

PadFindPoint(vgt f nl1nes,x,y,p"Mne,pco1) 
short vgt, nllnos, x, y; 
short *p11ne t •pcol ; 

Converts a set of world coordinates in x and y into a line and column position within a pad. Currently the 
vgt parameter is unused, and the number of lines must be specified in n 1 1 nes. 

24.8. Example Program 

ITic following program can be run cidicr under Unix or under the V system executive. The #if def VAX 
directives allow the programmer to conditionally compile code for one environment or the other, ft first 
creates an SDK and VGT, then displays 100 random objects of various kinds. 

/• 

• test.c - a test of the remote VGTS implementation 

• Bill Mowicki September 1982 
•/ 

# include <Vgts.h> 

# Include <Vio.h> 

# define Objects 100 ' /* number of objects •/ 
short sdf, vgt; 

Qu1t() 

C 

DeleteVGT(vgt.l); 

DeleteSDF(sdf); 

ResetTTY(); 

ex1t(); 
> 

main() 

£ 

1nt i; 
short item; 
long start, end; 
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ifdef VAX 

printf( "Remote VGTS test program\n") ; 
else VAX 

printf("VGTS test program\n") : 
endlf VAX 

fflush(stdout); 

GetTTY(); 

sdf * Create5DF() ; 

DefineSymbol( sdf, 1. "test" ); 

Addltem( Sdf, 2. 4, 40, 4, 60, MM, SDF - FILLED_RECTANGLE, NULL ); 

EndSymbol( sdf, 1, ); 

vgt • CreateVGT(sdf , GRAPHICS+ZOOMABLE. 1. "random objects" ); 

DefaultV1ew(vgt, 500, 320, 0, 0. 0. 0, 0, 0); 

time(&start): 

for (1-12; i<Objects; 1++ ) 

{ 

short x ■ Random( -2, 155); 
short y ■ Random( -10, 169); 
short top ■ y + Random( 6, 100 ); 
short right ■ x +■ Random( 4, 120 ); 
short layer * Random( NM, NG ); 



EditSymbol(sdf , 1); 
Deleteltem( sdf. i-10); 
switch (Random(l, 6) ) 

{ 

case 1: 

Addltem( sdf, 1, x. right, y. top, layer, 

SDF_FILLEDJ*ECTANGLE, MULL ); 
break; 



case 2: 

Addltem( sdf, i, x, x+1000, y, y+16, 0, SDF.SIMPLE_.TEXT, 

"Here is some simple text" ); 
break; 



case 3: 

Addltem( sdf. 1, x, right, y, y+1, 0, 
SDF_HORIZONTALJ.INE, MULL ); 
break; 



case 4: 

Addltem( sdf, 1, x, x+1, y, top, 0, 

SDF_VERTICALJ.INE. MULL ); 
break; 



case 5: 

Addltem( sdf, 1, x, right, y, top, 0, 

SOFJ3ENERALJ.INE, MULL ); 
break: 
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case 6: 

Addltem( sdf. 1, x, right, top. y, 0. 

SDFJ5ENERALJ-INE, NULL ); 
break; 

} 
EndSymbo1( sdf, 1. vgt ); 

> 

time(&end) ; 

if (end—start) end ■ start+1; 

pr1ntf("%d objects in Xd seconds, or %d objects/second\r\n", 

Objects, end-start, Objects/(end-start)); 
printf ("OonelXrVn"); 
Quit(); 



Random( first, last ) 

{ 

/• 

* generates a random number 

• between "first" and "last" inclusive, 
•/ 

1nt value ■ rand()/2; 
value X- (last - first + 1); 
value +• first; 
return(value); 

} 
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— 25 — 
Fields: Using a Pad as a Menu 



These routines allow you to set up a table of fields in a pad. They can be selected with the mouse, so that 
you can have a menu. The advantages over the standard pop-up menu are that you can have more choices, 
you can display more information with each choice, and the menu is always there. 

With each field, you can associate a value, which can be displayed and edited. 

The menu is an array of F 1 e 1 ds. These arc defined in <f 1 el ds . h>. Each Field consists of: 

typedef struct 

{ 

short row; ' /• field's row number in pad */ 

short col; /* leftmost character of field */ 

short width; /* width of field */ 
long *value; 
int (*proc)(); 

char *format; /* format in which to display *value */ 
} Field; 

row and col indicate where in the pad the field begins. (row= 1 and col = 1 is the top left comer of the pad.) 
width is the length of die field in characters. Only one-line fields arc supported, proc is not used by the 
package itself! The intended uscagc is: 

field » GetField(...); 

if (field) (*field->proc))(field->value); 

or perhaps: 

if (field) (•field->proc))(field); 

format is discussed below. 

25.1. Formats 

format is a format like those used by printf and scanf. Together with the value, it determines the 
string to be displayed in the field. This string must be a least wi dth characters long. It is a zero-terminated C 
(asciz) string. Formats arc of the form: 

prefix [conversion] suffix 

Here prefix and suffix is constant text which is displayed. If a % is to be displayed, it must be written as %%. 
The following utility routine will do a string copy analogous to strncpy, except that %s are automatically 
copied: 

char * StrToFortnat(f , s, n) 

char *f; /• destination string buffer where Ts arc to be doubled */ 
char *s; /* source string */ 
int n; /* count - buffer size •/ 

The optional conversion describes how val ue is to be displayed/ read. Its form is: 
XfHfQlTieldwidlhJf.precisionJfKJc 
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Here the % indicates die beginning of the conversion specification. The conversion type letter c marks the end 
of the conversion specification.' The format is exactly as used by pMntf, except that there may be a data 
length specification A. If value is a short * rather than a int *, X must be given as h. If the val ue is a 
doubl e * rather than a f 1 oat \ X must be 1, or the conversion type letter c must be capitalized. 

When fields arc displayed, sprintf is used to do the conversion. The length specification X is only used 
to dereference value (except for fields where die conversion type letter is s); it is stripped from the format 
before being passed to sprintf. 

On input to fields, only the length specification X and the type code care passed to sscanf. If the type 
code is e or g, it is changed to f . 

25.2. The Field Table as a Menu: Selecting an Action 

Field * GetField(menu, menuLength, buttons, pad) 

Field *menu; 

int menuLength; 

short buttons; 

File *pad; /* output pad */ 

If button 1- 0, it is assumed that the mouse is down on procedure entry. GetFi eld returns when the 
button state changes; if it changes to non-zero, GetFi eld fails by returning zero. If button -- 0, 
GetFi eld will first wait for an event. (It will fail unless it is a mouse button being pressed down.) 

As long as the user keeps the mouse button down, display the selected field (if any) in inverse video. When 
the user releases the button, return the last selected Field, or if none, return 0. 

The menu is terminated by the first negative row field, or when the menuLength count is exhausted. 

25.3. Displaying Fields 

PutF1eld(buffer, field) 

char *buffer; /• destination string buffer */ 

Field *f1eld; /* source format and value •/ 
More or less like sprintf ( buffer, f 1eld->format, *f 1eld->value). 

D1splayF1elds(menu, menuLength, pad) 
Field *menu; 
' int menuLength; /* see GetField function •/ 

File •pad; /* output pad where fields are to be written */ 

Display in the pad all the string fields, at the positions given by the row and col components. 

ITic width components arc ignored. This allows convenient display of material which the user cannot 
select ("writc-protcctcd" fields) cither by using fields with w1 dth <- or by having a str 1 ng longer than 
the width. 
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25.4. User Input to Fields 

EditField(f1e1d, stuff, out, 1n) 

Field *fie1d; /* field whose * value is to be edited */ 

1 nt stuff ; /* 0: old text should be cleared: 1: stuff into editor */ 

File *out, *1n; /* input and output sides of pad to use */ 
Move the cursor to the conversion part of the f 1 el d. If stuff is 0, the old value is cleared from the screen; 
if it is 1, die old value is placed in the line editing buffer. Enter line-edit mode, and wait for the user to type 
in a line. If the user types t<3, abort, redisplay old value and return -1. Else parse the line using 
f 1eld->format. If this succeeds, update *f iald->value, returning 1, else 0. In any case, redisplay 
things correctly. 

Ed1tStdFld(f1eld) 

Equivalent to EditField(f1e1d, 1, stdout, stdln) 



ReadStdFld(fielcl) 
EquivalcnttoEd1tF1eld(f1e1d, 0, stdout, stdln) 

25.5. An Example 

/* This is a program which adds up integers, optionally scaled •/ 

^include <std1o.h> 

^include <fie1ds.h> 

double Scale - 1.0, Total - 0.0; 

int Value » 0; 

Qu1t() { ... cleanup actions ... ; exit(-l);} 

NewValue(f) 
Field *f; 

{ 

if (ReadStdFld(f) — 1) 

Total +- Value * Scale; 

} 
Fields Menuf] ■ 

/* VAL (defined in fields. h) coerces pointers and values to (1nt *) •/ 
{1., 41. 10. VAL &Scale. EditStdFld, "Scale: X6 "}, 
{1. 1, IS, VAL &Value, MewValue, "New value: %-8d"}, 
{2, 1, 0, VAL&Total, 0, "Total: %G. "}, 
(5, 1, 8, 0, Quit, "—Quit—"}. 
LASTFIELD /* defined in fields. h •/ 

}: 

ma1n() 

{ Field 'field; 
while (1) 

putc('L* & 31, stdout): /* write FormFeed to clear screen •/ 
D1sp1ayFields(Menu. 999, stdout); 
field - GetField(Menu, 999, 0, stdout); 
if (field) (*(field->proc)) (field); 

> 
} 
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Since the screen is updated every time here, we do not have to worry about garbage being lea behind when 
the field becomes shorter. However, I have shown two solutions which can be used when this is not desired: 
In the Val ue field, we make sure die field doesn't become shorter, by left justification if needed. This loses if 
we want to output punctuation after the value, as in the Total field. In tiiis case, we can make sure that we 
output enough trailing spaces to erase the garbage. 

25.6. Limitations 

No facilities yet for arrays. 
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SUN PROM MonitorEmulator Traps 



The emulator trap interface functions in the V C library are listed below. These are extremely dependent 
on the version of the SUN workstation prom monitor being used. The use of these functions should be 
avoided if at alt possible; none of them are present in the Unix C library. For more information sec the Sun 
User's Guide. Note that not all the traps mentioned there are available under die V kernel, since processes 
always run in user state. 



1nt emt_getconf1g() 

Returns the current value of the "configuration register. 

int amt_getmems1ze() 

Returns the size of the on-board RAM in bytes. 



char emt„getchar() 

Busy-wait input from the console. Will not work unless the kernel console device is closed to prevent it from 
"stealing" the characters. 



1nt emt_putchar(c) 
char c; 

Busy-wait output to the console. 



Int emt_t1cks<) 

Returns the number of milliseconds since the monitor was last booted. Incremented at each memory refresh. 



1nt emt_vers1on() 

Returns the version number of die PROM monitor. 



1nt fbmode(newmode) 
1nt newmode; 

Queries/sets the frame buffer mode. 



setecho(flag) 
1nt flag; 

Controls whether characters read using emt_getchar ( ) are echoed. 



V-SYSTI-M 5.0 RI'1-HRKNCB MANUAL PROGRAM ENVIRONMENT 



132 MISCELLANEOUS FUNCTIONS 



V-SYSriiM 5.0 RHR-RI-NCE MANUAL PROGRAM ENVIRONMENT 



MISCELLANEOUS. FUNCTIONS 133 



— 27 — 
Miscellaneous Functions 

27.1 . Time Manipulation Functions 

The time-related functions in the V C library are described below. A few of diem arc not present in the 
Unix C library. 

st1me(), t1me(), ft1me() 

These arc Unix system calls and arc implemented here with simple library functions which emulate the Unix 
functions by performing the appropriate V kernel operations SetT1me( ) and GetTime( ). They have the 
same interface and functionality as in Unix; however, f t1mo( ) has die Umczonc hardwired as Pacific Time, 
since the V-Systcm provides no time /.one information. 

ct1me(), 1ocaWnie(), gmt1me(), asct1me(), t1mezone() 
These arc identical to the Unix library functions. 



sleep(secdnds) 

unsigned seconds; 

The invoking process is suspended from execution for the specified number of seconds. The actual time may 
be considerably longer dian that specified if the process is not the highest priority ready process when its sleep 
time expires. sleep() is not sensitive to Wakeup()'s. Use die V system call Delay() for a 
Wakoup( )-ablc suspension. 

unsigned GetRemoteT1rae() 

Returns die time according to die TIM K.SKRVKR in seconds since January 1, 1970, GMT. Returns zero if it 
fails, e.g., no time server responded. Currently die Unix servers act as time servers. 

27.2. Strings 

The string-related functions in die V-Systcm C library arc described below. 

27.2.1 . Unix String Functions 

The following functions arc identical to the functions of the same name provided by Unix. Sec the Unix 
Programmer's Manual for documentation. 

atof() atoi() atol() crypt() 

ecvt() gcvt() index() rindex() 

stpcat() strncat() strcinp() strncmp() 

strcpy() strncpy() strlen 
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27.2.2. Verex String Functions 

There is also another set of string manipulation functions which were ported from Verex. These include the 
following: 



1nt Any(c, string) 

char c; char *str1ng; 

Determine whether there is any occurence of the byte c in the string string, and return true (nonzero) if so, 
else false (zero). 

char *Concat(dest, si, s2, s3) 
char *dest, *sl, *s2, *s3; 
Concatenate the strings si, s2, and s3, store the result in dest, and return dest. dest must have enough 
room to store die rcsulUng string. If any of si, s2, s3 are aull pointers, the remaining arguments are 
ignored. 

1nt ConvePt_num(stPlng, del 1m, base) 

chap *stp1ng; chap **del1m; unsigned base; 

Parse the given string to extract a number of base base and return its value. If base is zero, the initial 
character of die string determines the base, as follows 

# Base 2 

(zero) Base 8 

$ Base 16 

otherwise Base 10 

Upon return, * del Ira is modified to contain a pointer to die delimiter that terminated the number. 

chap *Copy_stP(stPlng) 
chap *stp1ng; 

Copy the given string into a newly allocated region of memory and return a pointer to the copy. The new 
region is allocated using malloc( ) and may thus be freed using f pee( ) when ihc copy is no longer needed. 



1nt Equa1(sl, s2) 
chap *sl. *s2; 

Compare the strings si and s2. Return true (nonzero) if the strings are equal, else false (zero). Strings arc 
considered to be equal if and only if they arc of equal length (up to die terminating null byte) and each 
corresponding byte is die same. 



1nt Hex_value(c) 
chap c; 

Return the value of c, interpreted as a hex digit. Return -1 if c is not a hex digit. 



chap *Lowep(stPlng) 
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char *str1ng; 
Convert all alphabetic characters in stpl ng to lower case and return str 1 ng. 

unsigned Null_stp(stping) 

char *str1ng; 
Return true (nonzero) if string isanull string (i.e., oflength zero), else return false (zero). 

char *ShiftJleft(stPing, chars) 
char *stp1ngi: unsigned chaps; 

Delete the leftmost chaps characters of string by shifting the remaining characters to the left, and return 
stP 1 ng. stP 1 ng must be at least chaps characters long, but this condition is not checked. 

unsigned S1ze(stp1ng) 
chap *stping; 

Return the number of characters in the given string, i.e., the index of the null byte that terminates the string. 



chap *Uppep(stPlng) 

chap *stp1ng; 
Convert all alphabetic characters in string to uppercase and return string. 

27.3. Other Functions 



qsoPt(base, nel , width, compare) 

chap *base; 1nt nel. width; 1nt (*compape)() ; 

Implements the quicksort algorithm, base is a pointer to the base of the data; nel is the number of 
elements; width is the width of an clement in bytes; and compare is a function to compare two elements. 
The function compare must return an integer less than, equal to, or greater than zero, if the first argument is 
less than, equal to, or greater than the second, respectively. 



setjmp(env) 

jmp_buf env; 

longjmp(env, value) 

jmpj)uf env; 1nt value; 
set jmp( ) saves the stack environment in env, so that a later call to longjmp( ) will act like a return was 
made from die function which contained the call to set jmp( ), with return value val ue. 

chap *EppopStPlng(epPOP) 
SystemCode eppop; 

Returns a pointer to a string describing the system request or reply code sppop, in human readable terms. 
Use Uits in error messages instead of printing the numeric value of die code. 
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PrintError(error, msg) 

SystemCode errop; char *msg; 
Prints die string msg and an explanation of the SystemCode er pop on the standard error file. 
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Part III: 
Servers 
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Servers Overview 



AH system services other than those implemented by the kernel are provided by sending a message to one of 
the system server processes. This manual describes the protocol for requesting these services, including the 
format of the request message, the format of the reply message, the possible values for the message fields, and 
the process that handles the request. This information is generally not required by application programmers 
because the protocol is implemented in a library of standard functions that provide system services via simple 
function calls. The library is described in the V-System program environment manual. More sophisticated 
use of the system requires the more detailed information in this manual. 

This chapter describes some general message format standards used in communicating with servers. The 
next two chapters give details of two standard protocols, the V-Systcm I/O Protocol and V-Systcm Naming 
Protocol. The remaining chapters give the details of the particular servers, describing which of these protocols 
they implement, additional server-specific request types they provide, and the server-specific semantics of the 
services and requests each implements. . 

28.1 . Message Format Conventions 

System server protocols obey several system-wide conventions. The first short word of every request 
message contains a request code indicating the service requested. The first short word of every reply message 
contains a code indicating the successful completion of the request execution or the reason that die request 
was not executed normally. A requesting process can assume that tine request has been completely executed 
when the reply message is received with a successful reply code (although in cases such as disk write-behind 
tli is may not be strictly true). 

28.2. Standard System Request Codes 

Hach system request is allocated a unique request code to be placed in the first word of the request message 
when requesting that service. Hie request codes obey the message format conventions imposed by the kernel, 
as described for Send( ) in the V environment manual. The manifest constant definitions for these request 
codes arc defined in the standard C include file <Vcnviron.h>. 

28.3. Standard System Reply Codes 

The reply code returned in a message from a server is normally one of the following standard system 
replies: 

OK Operation successful. 

ABORTED An operation was aborted. For example, a network connection that has been aborted 

returns this code. 

BAD.ADDRI^SS Request contains an invalid memory address. 

BAD.ARGS Request contains ficld(s) with illegal or inconsistent values. 

BAD.BLOCK.NO 
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The block number specified in an I/O request docs not specify an existing block. If the file 
instance has attribute STREAM, the block number docs not specify the block which is 
sequentially next in reading or writing. 

BAD.BUFFER A buffer specified in the request lies (perhaps partially) outside the client's address space. 

BAD BYTE.COUNT 

The byte count is larger (or smaller) than that supported by the server. On a file instance 
without the MULT1JJLOCK attribute, this is returned if the number of bytes requested to 
read or write is greater than the block size. 

BADJ>R0CESS_PR10R1TY 

The request specified an illegal value for a process priority. 

BADJSTATE Request invalid at this time. 

BUSY Hie server cannot satisfy the request at this time, probably because the requested resources 

arc allocated to another client 

CURRENT JTONTF.XTJNVALID 

Normally only returned by library routines, not servers. The routine has detected that the 
current context of the calling process is invalid, probably because its process-id component 
refers to a nonexistent process. 

DEVICE.ERROR 

File or device-dependent error has occurred. 

DUPUCATFJMAMK 

'I"hc request attempted to assign the same name to two different objects. 

ENDJDF.FILE Attempt to read beyond file boundaries. 

ILLEGAL.REQUEST 

Invalid request code. The request was probably sent to the wrong type of server, one which 
could not perform that function, 

INTERNAL.ERROR 

'Hie server detected an inconsistency in its own suite. This error code may indicate a bug in 
the server. 

INVAUD.CONTEXT 

The request contained a context identifier (sec chapter 30) that was invalid. 

INVAUD.FILEJD 

The request contained an invalid file instance identifier. 

INVAUD.MODE 

'Hie mode specified as part of a CRHATHJ NSTANCK request is not valid. 

IO.BREAK Returned from interactive files. 

KERNEL.TIMEOUT 

A timeout occurcd in the kernel when trying to send to a remote process. This error differs 
from NONEX1STEN T_PROCESS in that the sending kernel did not receive a negative 
acknowledgement from the remote kernel, but for most purposes it can be handled in the 
same way. This error code is only generated by the kernel, but may be passed on by other 
servers. •- . 

MODE_NOT_SUPPORTED 
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The mode specified as part of a CREATEJNSTANCE request is not supported by this 
server. ' 

NOJvtEMORY The server was not able to obtain enough memory to satisfy the request. 

NO_PDS The server was not able to create a process or team needed to satisfy die request. 

NCLPERMISSION 

Some kind of restricted operation was attempted. 

NO.SERVER.RESOURCES 

The server has (temporarily) inadequate resources to satisfy the request. 

NONHXISTENT.PROCESS 

The request was sent or forwarded to a nonexistent process, or a nonexistent process was 
specified in the request. This error code is only generated by the kernel, but may be passed 
on by other servers. 

NONEXISTENT.SESSION 

The request referred to a session (see chapter 36) which docs not exist, or to an object 
which is not a session. 

NOTjWVAlTINGRKPLY 

The process specified in a request was not awaiting reply from the client. 

NOT_ FOUND The object named in the request was not found. 

NOT.READABLE 

Specified file instance docs not have the attribute READABLE which is required for the 
requested operation. 

NO'LWRiTEAm.E 

Specified file instance docs not have the attribute WRITEABI.E which is required for the 
requested operation. 

POWER .FAILURE 

Operation was unsuccssful due to a power failure. 

REQUEST_NOT_SUPI>ORTED 

The server recognizes the request, but docs not support it. 

RETRY Client should repeat request, 

SERVER.NOTJIESPONDING 

The server failed to receive a response from another server specified in the request. 

TIMEOUT An attempt to satisfy the request failed because of a timeout. Usually applied to network 

connections. 

The ErrorStr1ng() function described in the V Environment manual will return a character string 
version of many of die system reply and request codes. The string form is much more informative than 
printing die codes in numeric form. 
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The V-Systern !/0 Protocol 



A standard input/output protocol is defined in V to provide transfer of data between processes in a uniform 
fashion. Using this protocol, a client process views and accesses data managed by a server process as a file. A 
file is a "view" of the data associated with an object or activity managed by a server. An object viewed as a 
file is a sequence of variable-size records or blocks. 

To operate on an object viewing it as a file, it is necessary to create an instance of that file. The protocol is 
object-based in die sense that it is defined in terms of operations on a object, the file instance. File instance 
operations include: creating a file instance, querying a file instance, setting the file instance owner, reading, 
writing, and releasing file instances. There arc also operations for setting a prompt string and break process 
associated with a file instance which arc restricted to interactive file instances. A server diat supports tin's 
protocol is called an I/O server or file instance server. (The term "file server" might be more appropriate if it 
did not have a different established meaning in the research literature on distributed systems). 

A file instance is created by a server in response to a client request, which specifics the file, i.e. die object or 
data and the particular view and usage required. Conceptually, a file instance is an object which is created at 
the time of the client's CREATKJNSTANCE request, and (possibly) initialized to contain die same data as 
an existing, permanent file. When the instance is released by the client, the data contained in the instance is 
atomically written back to the corresponding permanent file. For some servers (for example, the internetwork 
server), however, there is no permanent file corresponding to an instance, while for others (for example, the 
device server), there is effectively no distinction between the instance and die permanent file - changes in the 
instance arc immediately reflected in the underlying file or I/O device. The current implementation of some 
storage servers (e.g., the V Unix server) also causes changes in an instance to be immediately reflected in the 
underlying file. 

A file instance is uniquely identified by die server process identifier and the instance identifier returned by 
die CRF.ATKJNSTANCK request. Hie creating process is made die owner of the file instance. The lifetime 
of the file instance and the validity of die instance identifier docs not exceed that of the owner of the file 
instance. The owner of a file instance can be changed by UicSKI JNSTANCKJDWNHR request. 

Hie reply message to a CRRATHJNSTANCK or QUKRYJNSTANCK request specifics the server, file 
instance identifier, block length in bytes, file type, last block (written) in die file instance, number of bytes in 
die last block, and the next block to read. 

The file type indicates the operations that may be performed on die file instance as well as die semantics of 
these operations. These types arc defined in die include file <Vio.h>; file types arc specified as some 
combination of die following attributes. 

RFADABLK RlvADJNSTANCE operations arc allowed on the file instance. 

WR1TEABLE WRITEJNSTANCE operations arc allowed on die file instance. 

APPEND.ONLY WRITEJNSTANCE operations arc only effective to bytes in die file instance beyond the 
last byte associated with the instance at the time it was created. 

STREAM All reading and writing is strictly sequential. The first READJNSTANCK operation must 

specify die block number returned as nextblock in the reply to the CRKATEJNSTANCE 
request This next block number to read is incremented after each RHADJNSTANCE 
operation. Its current value is returned by a QUKRYJNSTANCK. A server must store 
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the last block read and allow it to be read again, to provide duplicate suppression on 
requests. 

Similarly, each WRITE INSTANCE operation must specify the block number returned as 
lastblock by CREATE "INSTANCE or QUERYJNSTANCE. This block number is 
incremented after every write operation. A server must ignore requests to rewrite the last 
block written, returning a reply code of OK, to provide duplicate suppression on requests. 

A file instance without the STREAM attribute stores its associated data for non-sequential 
("random") access. That is, on a non-stream file, for any n, block n may be read or written 
at any dme, and reading block n will return the same data as was last written to block n. 

Since each file models a single sequence of data blocks, objects which provide bidirectional 
communication, such as serial lines or network connections, are most appropriately 
modeled as a pair of file instances, one a READABLE STREAM, the other a 
WRITEABLE STREAM. Some servers may allow both instances to be created by a single 
CREATEJNSTANCE request 13 

FIXED LENGTH 

The file instance is fixed in length. The length is specified by the last block and last byte 
returned from a create or query instance request. Otherwise the file instance grows to 
accommodate the data written or else the length of die file instance is not known (as in the 
case of terminal input). 

VARIABLE.BLOCK 

Blocks shorter than the full block size may be returned in response to read operations other 
than due to end-of-file or other exception conditions. For example, input frames from a 
communication line may differ in length under normal conditions. 

With a file instance that is VARIABLE.BLOCK, WRITEABLE, and not STREAM, 
blocks that arc written with less than a full block size number of bytes return exactly the 
amount written when read subsequently. 

MULTLBLOCK Read and write operations arc allowed that specify a number of bytes larger than the block 
size. 

INTERACTIVE 'Hie file instance is a text line-oriented input stream on which a prompt can be set using the 
SITJ'ROMPT request and a break process can be defined using the 
SKI'JWEAKJ^OCESS request. It also has the connotation of supplying interactively 
(human) generated input 

Not all of the possible combinations of attributes yield a useful file type. The file instance types supported 
by each server arc documented with each server. 

A client must specify a mode of usage for the file instance when creating it 'Hie mode is one of FREAD, 
FCREATE, FMODIFY and FAPPEND. The modes of usage have die following semantics. 

FREAD No write operations arc to be performed, only reads. 

FCREATE Any data previously associated with die described file is to be ignored and a new file 



13 A few existing servers bend this rule by assigning the same instance id to the input and output streams, even though block number n 
of the input stream. Ls unrelated to block number n of the output stream. Strictly speaking, this behavior is in violation of the protocol, 
and we plan to change these servers eventually. A single STRI-AM that is both RI-ADABLl- and WRITEAM.E would have to return 
the data written to block n ir block n Ls later read back, This type of file might be used to model a Unix-like pipe, but in fact, the 
V-Systcm pipe server (sec chapter 33) takes a different approach, creating a separate instance for each end of the pipe, with the 
connection between them invisible to the protocol. 



V-SYSTEM 5.0 REFERENCE MANUAL SERVERS 



THE V-SYSTEM I/O PROTOCOL 



145 



instance is to be created. Write operations arc permitted; read operations are also 
permitted if the file instance has type attribute READABLE. 

FAPPEND Data previously associated with die described file remain unchanged. Write operations are 

permitted only to append data to the existing data. 

FMODIFY Existing data is to be modified and possibly appended to. Both read and write operations 

arc required. This is only supported on file instances that arc not STREAM. 

A server creates a file instance of a suitable type for the specified usage mode if it can. For example, the 
storage server provides file instances with type attributes READABLE, FIXEDJ.ENGTH and 
MULTLBLOCK in response to a CREATEJNSTANCE request specifying FREAD usage mode. 

One of three modifiers may be used on the mode field of a CREATEJNSTANCE request 

FD1 RECTORY Indicates that the given name specifics a context directory. See section 30.7. 

FEXECUTE Specifics that the given file is to be executed as a program on the storage server machine. 
The mode must be FREAD or FCREATE. Respectively, one or two file instances are 
returned, which allow reading from the program's standard output, and optionally (in 
FCREATE mode) writing into its standard input When two instances arc created, the 
filcid of the second (readable) file instance is obtained by adding 1 to the filcid of the 
writcablc instance (which is returned in the reply message). This mode modifier need not 
be supported by all storage servers. 

FSESSION Specifics that a session is to be created on die server machine, using the (null-separated) 

user name and password passed in the filename field of the ■CREATEJNSTANCE 
request 'ITic file server pid returned is the process id of the session. Releasing the file 
instance id returned will terminate the session. The session will also be terminated after 
the death of the instance owner. This mode modifier is only supported by storage servers 
that use the concept of "session." Sec section 36. 

'ITic following subsections give the format of the request message and the format of the reply, plus a 
description of the semantics for each operation in the protocol. These message formats arc defined in the C 
include file <Vioprotocol.h>. • 



29.1 . CREATE INSTANCE 



rcqucstcodc CREATEJNSTANCE 

filcnamcindcx 'Hie index of the first byte in the filename to use in the name mapping. 

type Type of file to create an instance of. This is used, for example, to specify the device to the 

device server and protocol to the internet server. 

filcmodc I3csircd usage mode indicating FREAD, FCREATK. FAPPEND or FMODIFY, plus 

optionally FDIRECTORY, FEXECUTE, or FSESSION. 

unspecified Server-dependent in formation specifying the file to be created. 

contextid Specifics the context within die server in which die filename is to be interpreted. (Sec 

section 30.2.) 

filename Pointer to a byte array containing the symbolic name of the server or file. 

fitcnamclcn Number of bytes in filename, not including the terminating null byte. 
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rcplycode Standard system reply. If the reply code Is not OK, the file instance was not created and 

the remainder of the reply is not defined. 

fileid File instance identifier. This is the number used in subsequent operations on the file. 

filcservcr Process identifier of the server managing diis file. This is not necessarily the same as the id 

to which the request was sent. 

blocksizc Maximum size in by tes of a block. 

filctype Type attributes of the file instance as described at the beginning of this section. 

filciastblock Index of the last block in the file or of the last block written to die file instance if it is a 

STREAM file. Indexing is 0-origin. 

filclastbytes Number of bytes in the last block. For file instances which arc not WRITFABLE and not 

FIXED.LENGTH, this field and the filelastblock field should return the maximum 
unsigned integer. 

filcncxtblock Number of the next block that can be read if this file is a READABLE STREAM. 



The CREATHJNSTANCE request is issued cither directly to the server or sent via a name server process. 
In the former case, the use of the fields of die request is server-dependent and is documented for each server. 
In the latter case, the unspecified field is not filled in by the client The name server maps the symbolic name 
to a server and a server-dependent description of the file and then forwards the request to the appropriate 
server. An I/O server may not use the filename, flenamelen, and filenameuuiex fields if it docs not support 
symbolic naming. 

The fileid and f/eserver uniquely identify the file instance created. The file instance exists until released or 
until the requesting process ceases to exist. 



29.2. QUERY INSTANCE 



rcqucstcodc 
fileid 



QUKRYJNSTANCK 
File instance identifier. 



rcplycode A standard system reply. If the reply code is not OK, the file instance was not queried and 

the remainder t>f the reply is not defined. 

fileid File instance identifier, same as the request for compatibility with the reply to the 

CRHATUJNSTANCK request. 

filcscrver Server process identifier. 

blocksize The maximum size in bytes of a block. 

filctype Type attributes of the file instance as described at the beginning of the section. 

filelastblock Index of the last block in die file or the last block written to the file instance if it is a 

STREAM file. Indexing is 0-origin. 

filclastbytes The number of bytes in die last block. 
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filcncxtblock Number of die next block that can be read if the file is a READABLE STREAM. 



In response to a QUERYJNSTANCE request message, the server queries the file instance specified by 
filcid for the parameters supplied in the reply message. The reply message has the. same format and semantics 
as the reply to a CREATE JNSTANCE request except for the reply code. For example, a reply code of 
NO'LFOUND to a CREATKJNSTANCE request indicates that the file specified docs not exist, while a 
rcply'codc of INVALID.FILEJD to a QUERYJNSTANCE request indicates the file instance docs not 
exist 



29.3. RELEASE INSTANCE 



requestcode RRLEASEJNSTANCE 

filcid File instance identifier 

rclcascmodc Server-dependent action to perform when releasing the instance. This field is set to zero 

on a normal close. 



rcplycodc 



A standard system reply code. 



' In response to a RELEASHJNSTANCF. request, the server invalidates the instance identifier, reclaims 
server resources dedicated to the instance and possibly performs some server-dependent function with die file 
instance data. A releasemotte of indicates normal completion of the use of the file instance. For example, in 
the case of the printer server, the file instance data is printed. In the case of the storage server, the data 
atomically replaces die previous version of die stored file data. A non-zero release mode causes the data to be 
discarded. 

A server may release a file instance with a non-/.cro release mode if it detects that the process that created 
the instance no longer exists. A server should maximize the time before reusing a file instance identifier. 



29.4. READ INSTANCE 



requestcode 

filcid 

block number 

buffcrptr 

bytccount 



READJNSTANCE 

File instance identifier 

Index of the block in the file from which the read is to begin.. 

Address of the data buffer in which the data is to be moved if more than 
IO_MSGJHJI'T'KR bytes arc read. That is, 10JV1SGJJUFFHR is the maximum number 
of data bytes that fit in die message. 

Number of bytes to be read. 



rcplycodc . Standard system reply code. 

filcid Same as in request 

shortbuffcr IO_MSGJiUFFER bytes containing the data bytes read if less than or equal to 
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IO_MSG_BUFFER bytes, 
by tecount Number of bytes read. 



In response to a READ INSTANCE request, the server transfers up to bytecount bytes from the file 
instance starting at the block numbered blocknumber. If the number of bytes read s less Uiar i the number 
requested the reply code indicates the reason. If the file instance has the type attribute VARIAIN.hJ3LOU^ 
and the block being read was not the full block size specified for the file instance, this case is not an error, and 
the reply may be OK, or END OF FILE if the last block was read. Note that a client may ignore the reply 
code if the returned byte count" is equal to die requested byte count, so servers should set the byte count to 
zero on error conditions. 

If the number of bytes read is less than or equal to lOJVISGJiUFFER, the data read is contained in the 
reply message starting at shortbuffcr. If it is greater than 10.MSG JiUFFER, the data read is transferred into 
the space of the requesting process starting at the address bujferptr. 

If the file instance has the type attribute STREAM, the block number specified must be the next block to 
read for this instance, which is incremented after the read. Reads always start at the beginning of die 
specified block ITic values of bytes read that were not explicitly written arc undefined. The number ol bytes 
requested must be less than or equal to the block size unless the file instance has the type attribute 
MULT1JU.OCK. 

29.5. WRITE INSTANCE 



rcqucstcodc WRITE INSTANCE, or WRITESHORTJNSTANCE if bytecount is less than or equal to 

iojviscLbuffer. 

filcid File instance identifier. 

blocknumber Index of the block in the file instance at which the write is to begin. 

shortbuffcr Data bytes to be written if less than or equal to IOJV1SG J*UFFER. 

bufTcrptr Address of the data buffer if no more than lOJvlSGJIUFFER bytes are being written. 

Otherwise, this field may be overwritten by the data bytes. 

bytecount Number of bytes to be written. 



rcplycode Standard system reply code, 

bytecount Number of bytes written. 



In response to a WRITEJNSTANCE or WRITESHORTJNSTANCE request, the server transfers up to 
bytecount bytes to the file instance sauting at the block numbered blocknumber. If the number or bytes 
written is less than the number requested, the reply code indicates the reason. As with READJNSTANCE, a 
client may ignore the reply code if the returned byte count is equal to die requested byte count, so servers 
should set the byte count to zero on error conditions. 

If the number of bytes to write is less than or equal to JOJV1SG JHJFFER, the data is assumed to be 
contained in die request message starting at shortbuffcr. If it is greater than 10_MSGJ*UFFER, the data is 
transferred from die space of die requesting process starting at die address bujferptr. Writes always start at the 
beginning of the specified block. Note diat die separate request code WRITESHORTJNSTANCE is used 
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when the data is contained in the message only to be consistent with the kernel message format conventions. 
There is no READSHORTJNSTANCE needed because the data is passed back in the reply. That is, 
WRITEJNSTANCE specifies that segment access is being passed while WR1TESHORTJNSTANCE 
specifies no segment access. 

If the file instance has type attribute STREAM, the block number specified must be one greater than the 
last block in this file instance, which is incremented after the write. The number of bytes to write must be less 
than or equal to the block size unless the file instance has the type attribute MULTIJ5LOCK. 

29.6. SET INSTANCE OWNER 



requcstcode SETJNSTA NCE.O WNER 

filcid File instance identifier 

instanccowncr Process identifier of new file instance owner. 



rcplycodc Standard system reply code. 



In response to a SHTJNSTANCEJDWNER request, the server sets the file instance owner process to that 
specified by instanceowtwr. The requesting process must be the current owner of the file instance. The initial 
owner of a file instance is the process that created the instance. 

29.7. SET BREAK PROCESS 



requcstcode S ET HR EA K.PROCESS 

filcid File instance identifier 

brcakproccss Process to be "broken" when next break generated on this file instance. 



rcplycodc Standard system reply code. 



In response to a SHTJIREAKJ'ROCESS request, the server sets the break process associated with die file 
instance to the process specified by brcakproccss. When a break is generated on this file (the IOJIREAK 
reply returned to any outstanding read operations), the server issues a Destroy Process kernel operation on the 
specified process. 

This request is only supported on flic instances with type attribute INTERACTIVE. 
29.8. SET PROMPT 



requcstcode SET..PROMPT 

filcid File instance identifier 
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promptstring Prompt string, which must be less than IO.MSG.BUFFKR bytes long. 



rcplycode 



Standard system" reply code. 



In response to a SET PROMPT request, the server sets the prompt string output previous to every read 
operation to that specified. This request is only supported on file instances with type attribute 
INTERACTIVE. 



29.9. QUERY FILE and NQUERY FILE 



rcqucstcode 
filcid 



QUERY.F1LE 

File instance identifier 



rcqucstcode NQU KR Y.Fl LE 

namcindcx ITic index of the first byte in the file name to use in the name mapping. 

unspecified Up to the last three 32-bit words in the message. 

namccontcxtid Context in which die name is to be interpreted. 

nameptr Pointer to a memory segment containing the file name. 

namclcngth 1 -cngth of the segment in bytes. 



rcplycode Standard system reply code, 

unspecified Server dependent information. 



In response to a QUERY Fll .1? or NQUERYJ ; ILK request, die server returns server specific information 
about the file or file instance. For example, the VGTS returns the "cooking" bits, and the internet server 
returns connection information. A QUERYJ-ll ,E request specifies the file using an instance identifier, while 
a NQU ERYJ-'ILH request uses a character-string name. Both types of request return die same information. 

29.1 0. MODIFY FILE and NMODIFY FILE 



rcqucstcode MODIFY JHLP. 

filcid File instance identifier 

unspecified Server-dependent information. 



rcqucstcode NMODIFY.FILE 

namcindcx 'Hie index of the first byte in the file name to use in the name mapping. 
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unspecified Server-dependent information. Up to the last three 32-bit words in the message, 

namccontextid Context in which the name is to be interpreted, 

nameptr Pointer to a memory segment containing the file name, 

namclcngth 1 xngth of the segment in bytes. 



rcplycodc Standard system reply code. 



The MODIFY.FILK and NMODIFY.FILE requests are supported by some servers to modify some 
attributes of the file or file instance. For example, die VGTS uses MODIFY.F1LE to turn echoing on and 
off. • 

A MODIFY.FILE request specifics which file is to be modified by passing an instance identifier, while an 
NMODIFY J«"7LE request passes a character string name. ' 
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— 30 — 
The V-System Naming Protocol 



A number of V-System services use character string names to specify the objects to be operated on, and 
many standard message types include space for such a name. Examples include die CREATE. IN STANCE 
request and several other requests described above as part of the I/O Protocol. 

Name mapping in die V-System is performed by a collection of cooperating server processes rather than a 
single, monolithic "name server." The V-System Naming Protocol consists of a uniform format for request 
messages that contain symbolic names, and a small set of request types which must be handled specially by 
any server that implements the protocol. The protocol also specifies conventions for forwarding partially- 
interpreted requests from one server to another. 

30.1 . Character String Names 

Syntactically, a character string name (CS name) is a sequence of zero or more bytes, of a specified length or 
else terminated by a null byte. Operationally, a character string name is a byte string as above that is used to 
specify an object relative to a server that can interpret the name. There is no universal limit on the length of 
character string names., Two CSnamcs arc equal if and only if they arc byte-wise identical and equal in length 
(where a null in the name takes precedence over die length specification). 

Although CSnamcs may contain arbitrary bytes, they arc generally specified or chosen by die client (as 
opposed to the server) and are usually human-readable ASCII strings. 

The term character string name handling server (CSNH server) refers to any server that performs character 
string name mapping, regardless of what else it docs. The term CSname request describes any request 
containing a character string name that must be mapped in order to perform die requested operation. 

30.2. Contexts and Context Ids 

In general, die interpretation of a string name depends on the context in which the name is used. Formally, 
a context is a set of (name, objcct)-tuples. A context can have an arbitrary set of members in theory. In die 
V-System, the context of a name includes (1) die server to which die name is to be sent, and (2) the place 
within that server's naming hierarchy where interpretation is to begin, or more generally, the context within 
the server. A server is specified by its process id, while a context within a server is specified by a context 
identifier. A context identifier is a 32-bit identifier assigned by die server. Thus in general, a context is 
specified by a (scrvcr-pid, context-id) pair. 

Hiis definition docs not specify detailed semantics for contexts, leaving it to individual servers. This is 
similar to the I/O protocol where, for example, the semantics of writing to a tile instance is not specified but is 
server-dependent. 'ITius, each name server must specify the semantics of its contexts. Kor example, while a 
flic server may implement a purely hierarchical name space and only implement contexts diat modify die 
semantics of so-called relative pathnames, a internetwork server may implement contexts that correspond to 
different networks, or sets of hosts talking particular protocols, etc. 

A context-id has die same lifetime as the server. Thus, after a context-id is acquired by a client, there is no 
need (and no way) to release it when the client is finished using it. A context-id identifies die context itself, 
not an "instance" of the context. Therefore, we have made context-ids relatively long (32 bits). 
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Basically, character string name mapping is structured as three levels: server, context and CSname 
However a CSname may be structured hierarchically, as in the case of a filesystcm pathname. I he nam mg 
protocol is independent of this structure, though usually each component in a hierarchical name will be die 
character string name of a context in which the rest of the name is interpreted. 

It is expected that, given a character string name, a server and a context id, the interpretation of that 
character string name is fully specified independent of the operation requested. 

30.3. Weil-Known Context Ids 

We require that context-id (called DEFAULT.CONTFXD represent a valid context on every CSNH 
server In general DRFAULT CONTKXT should be a reasonable default for clients that arc not sure which 
context within a server a name should be mapped in, but do know die server. For example, a server that 
provides access to a Unix file system should map DEFAULT.CONTEXT to the root directory (known as 
"/"). A server that provides only one context should number it 0. 

Other small context identifiers (less than 16, say) arc reserved for use as "well-known" contexts. There is a 
need for some servers to publish certain context ids, similar to DlvFAULTJTON TKXI, and some servers 
may provide certain contexts which have special properties. Currently defined well-known contexts include 

DKFAUIT.CONTI'XT 

As described above. 

PUBLIC JTONTKXT 

Holds publically-available V programs on storage servers. 

LOGIN_CONTKXT , . . „,„,,- 

'.ITic home directory of the owner of a session, on storage servers Uiat implement the 

concept of a session. 

ANYJTON1F ^ ^^ ^^ ^ ^ ^ GKrj'II..K_NAMK and GRrr.CON'rKXT.NAMK 
operations. When returned by one of these operations, it indicates the name is an 
"absolute" name, valid in any context on the given server. When passed in the contextid 
Held of a GKT CONTF.XTJNAMF. request, it acts as a wild card, i.e., the server receiving 
the request may return die name of any context on the server specified in the request. 

30.4. Name Request Format 

AH V-Systcm request messages that contain CSnamcs arc built on a common skeleton, defined as die 
NamcRcqucst structure in die standard header file <Vnaming.h>. 

rcqucstcode Any valid request code that grants read access to a segment. 

nameindcx 'Hie byte ofTsct of die name, within the segment specified by the last two long words of the 

message. 

unspecified Request-specific information, up to die last three long words in the message, 

namccontcxtid A 32-bit identifier for the context in which this name is to be interpreted, 

nameptr Pointer to the segment containing the symbolic name, 

namelcngth Length of die segment containing the name. 
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The reply is not specified by this protocol because it is generally dependent on the operation requested. 

The name need not be first in the segment but is considered to start at the byte offset specified by 
nameindex. [f the name is not last in the segment, it must be terminated by a null. A CSNH server may reject 
a request if the total segment size is too long for it to handle. 

30.5. Name Parsing and Forwarding 

A CSNH server follows the following algorithm in handling a request containing a CSname. 

If die server does not provide pointers to contexts in other servers as part of its name space, it may interpret 
the name in any way it chooses. 

Otherwise, the server begins by looking at the name itself, not the request code. Since this request may 
have been directed to another server (to which it will eventually be forwarded by this algorithm), the request 
code is irrelevant at this point- 
Names arc ordinarily interpreted left-to-right, if the server implements hierarchical naming. The server 
initializes the variable CurrentConiext to the context id specified in the request. As each component of the 
name is parsed, it is looked up in the current context. If the name specifies a context, CurrenK'ontext is 
updated.. If the new context is implemented by some other server, the nameindex field in the request message 
is updated to point to the first character of the name not yet parsed, the namecontextid field is set to 
CurrentContext, and the request is forwarded to the server that implements the context. 

A server with a fiat name space may ignore the contcxtid field of requests, but it must set this field when 
forwarding requests to other servers. 

30.6. Standard CSNH Server Requests 

There arc several standard CSNH requests, which- should be implemented by all CSNH servers, and others 
which need only be implemented by context prefix servers (sec chapter 42), but may be implemented by 
others as well. All of the request and reply formats described below arc subsets of the ContcxtRcqucst 
structure defined in the standard system header file <Vnaming.h>. 

30.6.1. GET CONTEXT ID 



rcqucstcodc GKT.CONTKXTJD 

nameindex The byte ofFsct of the name, within the segment specified by the last two long words of the 

message. 

namecontextid Context in which to interpret the given name. 

nameptr Pointer to the segment containing the symbolic name. 

namclcngth Length of the segment containing the name. 



rcplycode Standard system reply code. 

scrvcrpid The scrverpid component of the named context. 

contcxtid The contcxtid component of the named context. 
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entry type Optional, server-specific type in formation. 

instanccid File instance id associated with die context, if any. Server-specific. 

otherinfo Optional, server-specific information. 



Given a CSnamc diat names a context, this request returns a (scrvcrpid, contcxtid) pair which identifies die 
same context 

30.6.2. GET CONTEXT NAME 



rcquestcode 

servcrpid 

contcxtid 

nameptr 

namclcngth 



GKr_CONTEXT_NAME 

The scrvcrpid component of the context for which a name is to be found. 

The contcxtid component of the context 

Pointer to a buffer in which the name is to be returned. 

Size of die buffer. 



replycodc Standard system reply code. 

servcrpid The scrvcrpid component of the context in which the returned name is valid. 

contcxtid The contcxtid component of the context in which the returned name is valid. 

nameptr The value provided is returned unchanged. 

namclcngth Length of the returned name. 



Returns a CSnamc corresponding to the specified (scrvcrpid, contcxtid) pair, if one is known to the server 
receiving the request plus the server and context-id required to fully qualify the CSnamc. The context-id 
returned will be ANY_CONTKXT. if possible, and the server will ordinarily be the one to which the request 
was sent 

Since the inverse mapping from (scrvcrpid, contcxtid) to CSnamc is not well-defined in general, a server 
may sometimes fail to satisfy this request despite its best efforts. Also, dicrc may be many possible choices for 
the name that is to be returned. Servers should attempt to return a name that is as informative to a human 
user as possible. 

30.6.3. GET FILE NAME 



rcquestcode GKl'_RLK_NAME 

instanccid A file instance id for the file whose name is desired, 

nameptr Pointer to a buffer in which the name may be returned, 

namclcngth Size of the buffer. 
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rcplycodc Standard system reply code. 

servcrpid The scrverpid component of the context in which the returned name is valid. 

contcxtid The contextid component of the context in which the returned name is valid. 

nameptr The value provided is returned unchanged. 

namclength Length of the returned name. 



Returns a CSname for the file associated with the specified file instance, plus the server and context-id 
required to fully qualify the file name. The context-id returned will be ANY.CONTEXT, if possible, and the 
server will ordinarily be the one to which the request was sent 

30.6.4. ADD CONTEXT NAME 



rcqucstcodc ADDJTONTEXT.NAME 

namcindcx The byte offset of die name, within the segment specified by the last two long words of the 
message. 

scrverpid Server pid to assign to name. 

contcxtid Context id to assign to name. 

cntrytypc Server-specific type information. 

instanccid ' Instance id associated with context, if any. 

otherinfo Server-specific. 

•namccontcxtid Context in which to interpret (or define) the given name. 

nameptr Pointer to the segment containing die symbolic name. 

namclength Length of die segment containing the name. 



rcplycodc 



Standard system reply code. 



The ADD.CONTEXTJSAME operation defines a new CSname to refer to an existing context. The 
existing context is specified in die (scrverpid, contcxtid) fields of the request. The specified CSname is 
interpreted according to the naming protocol, in die context specified by nanwamtexiid, until the mapping 
algoridim reaches a context in which die remainder of die name is not defined, at which point it is acldcd to 
that context 

This operation need only be implemented by context prefix servers, but of course all CSNH servers must be 
able to forward it in accordance with die naming protocol. 

30.6.5. DELETE CONTEXT NAME 



rcqucstcodc DELErE_.CONTF.XT_N AM E 

namcindcx The byte offset of die name, within the segment specified by the last two long words of the 
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message, 
namccontcxtid Context in which to interpret the given name, 
nameptr Pointer to the segment containing the symbolic name, 

namclength Length of the segment containing the name. 
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rcplycode Standard system reply code 

servcrpid The scrvcrpid component of the name's former value. 

contextid The contcxtid component of the name's former value. 

entry type Server-specific type information formerly associated with the name. 

instanccid File instance identifier formerly associated with the name, if any. 

othcrinfo Server-specific in formation formerly associated with the name. 

Delete the specified context name, making it no longer meaningful. The context associated with Ms name 
is not deleted. This operation need only be implemented by context prefix servers, but of course all CSNH 
servers must be able to forward it in accordance with the naming protocol. 

30.7. Context Directories and Object Descriptors 

Kach context consists of a set of (name, objcct)-tuplcs and is implemented by a server process. Hie 
discussion so far has concentrated on performing operations on specific objects and the protocol for 
specifying a particular object. However, an important aspect of system operation is supporting query 
operations about objects or sets of objects. A simple example is that of listing the names of all objects in a 
given context In general, one may wish to list a variety of information about objects in a context, perhaps 
ignoring some of the objects based on their properties. 

Kach CSNH server implements one or more context directories of objects that it manages. A context 
directory appears as a file of records, with each record specifying an object in the associated context. A 
directory file is accessed using die I/O protocol with the CRI«AT1UNSTANC1< request specifying the name 
of the context to be used. Hie l-DIRKCTORY bit is set in the mode field of such a request. A client can then 
use the standard I/O routines to read the contents of the directory and derive the information required. The 
selection of the information required is done by the client, not the server. Hie client may also be able to 
modify some or all of the fields of a directory record by writing it, using the standard I/O protocol. A server 
is not obligated to make ail fields presented in a directory modifiable. If a client attempts to change a 
non-modifiable field, that field should be left unaltered, but any other changes indicated in the request should 
be carried out. 

Hie FDfRRCTORY bit is primarily for the benefit of Vcrcx-likc file systems, which permit each node in 
the naming hierarchy to be (in Unix terms) both a file and a directory. It discriminates between access to die 
data content of such a node, and the context directory associated with it. Also, servers that do not implement 
character sting naming at all can use this bit to distinguish between requests to access one of the objects they 
manage and requests to read their context directory. 

Hach record in a directory starts with a descriptor- type field that specifics the format of the record describing 
die object. For space economy, diis field is an identifier that specifics a description of die record format 
stored elsewhere in a system database of such formats. (The standard formats and descriptor type identifiers 
are defined in the header filc.<Vdircctory.h>.) Applications can read a directory and extract the required 
information by referring to die descriptor- type Held and dicsc format descriptions, even when a directory 
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contains heterogeneous records. 

A similar query activity involves accessing the descriptor of a single object. For efficiency and consistency, 
this is supported by a separate READJ3ESCRJPTOR function on the object (as opposed to being subsumed 
by the context directory Facility), which returns the same record as found in the context directory. A 
corresponding WRITtLDESCRIPTOR operation is available for modifying an object's descriptor. 

There is no implication that a server need store information about objects as it is presented in a context 
directory. For instance, the Unix file system stores die names of files separate from their descriptors with the 
association provided by so-called "i-nodc numbers." A context directory entry in this case is fabricated 
dynamically by replacing the i-node number in each record by its descriptor. 

The standard descriptor reading and writing operations arc described below. The message formats used are 
described by the DcscriptorRcqucst and DcscriptorRcply structures defined in <Vdircctory.h>. 

30.7.1. READ DESCRIPTOR and NREAD DESCRIPTOR 



rcqucstcodc RHAD_DHSCRlPTOR or NR FA ^DESCRIPTOR 

namcindcx 'Hie byte offset of the name, within the segment specified by the last two long words of the 

message (NRFAD.DKSCRIPTOR only). 

filcid File instance id of the file whose descriptor is to be read (READJ)fiSCRl PTOR only). 

dataindex The byte offset from the start of the specified segment where die returned descriptor is to 

be placed. 

namccontextid 'Hie context id of the context in which die given name is to be interpreted 
(NRFADJ)FSCRIPTOR only). 

segmentptr Pointer to a buffer which contains the object name (for NRFADJ)FSCRIPTOR), and in 

which the descriptor is to be returned. 

segmcntlcn Length of the buffer. 



rcplycodc Standard system reply code, 

dataindex Returned unchanged, 

segmentptr Returned unchanged, 

segmcntlcn Returned unchanged. 



These request types provide a way of reading the descriptor (context directory entry) of a single object. 
RHADJWSCRIFIOR specifies the object by file instance id, while NRKAD.DFSCRIPTOR specifics it by 
CSnamc. 

30.7.2. WRITE DESCRIPTOR and NWRITE DESCRIPTOR 



rcqucstcodc WR1TEJDFSCRIPT0R or NWRITF..DKSCRIPTOR 

namcindcx 'Hie byte offset of the name, within die segment specified by the last two long words of the 

message (NWRlTH_DtiSCRlPTOR only). 
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f llc id Hie instance id of the file whose descriptor is to be modified (WRITE_DESCR1PT0R 

only), 
dataindex The byte offset from the start of the specified segment where the new descriptor value 

begins. 

namecontextid The context id of die context in which the given name is to be interpreted 
(NWRITEuDESCRIPTOR only). 

segmentptr Pointer to a buffer which contains the object name (for NWRITEJDESCRllTQR), and 

the new descriptor value. 

scgmcntlen Length of the buffer. 



replycode Standard system reply code, 

dataindex Returned unchanged, 

segmentptr Returned unchanged, 

scgmcntlen Returned unchanged. 



These request types provide a way of modifying the descriptor (context directory entry) of a single object. 
WRITK DESCRIPTOR specifics the object by file instance id, while NWRITR.DKSCRIITOR specifics it 
by CSnamc. The server will modify each field in the object's descriptor for which the value written differs 
from the existing value, if the field is client-modifiable and the new value is legal. A client normally uses one 
of these operations by first reading the descriptor, then modifying the field(s) of interest, and finally writing it 
back. 
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The device server provides access to the raw kernel-supported devices via the I/O protocol. It is 
implemented directly by die kerne! as a pseudo-process as opposed to being a normal process like other 
system servers. Consequently, it is always configured when the V kernel is used. However, the device server 
behaves as any other I/O server process as far as applications are concerned. 

The device server appears as a single process that supports different types of devices using die same I/O 
protocol. Access to a device is established by sending a create instance request to die pid returned by 
GctPid(DEVICE_SERVER, LOCAL J*ID), or, if die standard context prefix server has been configured, by 
prefixing the device name with die context name "(device]" in a create instance request or Opcn() call. Using 
die standard information returned by the create 'instance request, the device can then be accessed using I/O 
protocol messages, cither directly or by means of die standard I/O library routines described in chapter . 
'ITicrc arc also some device-specific operations defined for some devices. The currently supported devices arc 
described below. 

31.1. Ethernet 

The Ethernet interface is accessed by specifying a device name of die form emits, where r is replaced by the 
Edicrhct type, cidicr 3 for 3 Mbit experimental Ethernet, or 10 for standard Ethernet, and s is a suffix, which 
is null for the first Ethernet interface, a for die second, b for the diird. and so forth. Currently only one 
Ethernet instance may exist at a time and only one Ethernet interface is supported, and the name eihernet is 
defined as an alias for cither enetJ or enet/0, whichever is present 

'Hie standard header file <Vctherncth> defines Ethernet-specific information, including die Ethernet 
packet format and various constants such as KNKr_.MAX_.DATA, die maximum size of the data portion of 
an Ethernet packet. 

In a create instance request, the filcmodc must be FCREATE. The type of an Ethernet instance is always a 
readable, writcable, variable block stream. 

Read and write instance requests arc standard except for die Ethernet block format. Hie Rlhcrncl is only 
sensibly accessed as a block (or packet) device, as opposed to a byte stream. The Eihernet block format is 
exactly that expected by die interface, namely, on the 3 Mbit Edicrnct, one byte for destination, one byte for 
source, two bytes for Ethernet packet type, followed by some number of data bytes, and on the 10 MBit 
Ethernet, six bytes for destination, six bytes for source, two bytes for packet type, followed by data bytes. The 
number of bytes specified in a write and returned by a read includes the destination, source and type bytes as 
well asdic data bytes. 

An Ethernet-specific QUKRY_KILK request is supported diat returns die host number, the number of 
collisions, receiver overflows, CRC errors, receiver synchronization errors, transmission timeouts detected, 
and the number of valid packets received. The host number should be used as die source address for every 
packet transmitted. The format for the request and reply messages is given by die Query EnctRcquest struct 
defined in <Vcthcrncth>. 
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31.2. Mouse:The Graphics Pointing Device 

The mouse is a graphics pointing device. It provides a means of indicating a coordinate position plus 
signalling different states via its three buttons. The device server provides access to the mouse through the 
I/O protocol, thus viewing it as a file. 

The mouse file appears as a 10-bytc file divided into 3 major fields. The first two bytes specify die mouse 
button positions, the three buttons being the low-order dircc bits of the second byte. A bit with va ue 
indicates the button is up, otherwise down. The next 4 bytes specify its current X coordinate. 1 he last 4 bytes 
specify its current Y coordinate. The kernel updates this file according to the input from the device These 
fields are specified in <Vmousc.h> as buttons, xcoordinate and ycoordinate with MBU1 lONl, MRU I IOMZ 
and MBUTTON3 specifying the button bit field assignments in the buttons field. 

A create instance request for a mouse specifics the name mouse in the filename field. Only one mouse and 
one instance of that mouse arc currently supported. The filemode field of the create instance request must be 
FCREATE. The mouse file instance created is initialized to have X and Y coordinates of 0. It has type 
attributes READABLE. WRITEABLE. and FIXEDJ.ENGTH. 

Read and write requests must specify block and a byte count of 10 bytes. A read instance request returns 
10 bytes specifying the current state of the mouse "file." A read instance request is queued until a change to 
the mouse file occurs, providing no change has occurred since the last read request. Thus, for instance a 
mouse reader process that repeatedly reads from die mouse and updates a cursor is suspended when the 
mouse is not being moved and no button positions arc changing. Conversely, die read returns every time a 
change does occur. 

A write instance operation enanges the kernel-maintained record of the mouse button positions and the X 
and Y coordinates to that specified by the 10 bytes in the buffer. Setting the mouse buttons in the kernel has 
no significant effect because this record is updated to agree with Uk actual button positions on the next input 
(or "squeak") received from the mouse. 

There is no need to provide a query function that simply returns the current mouse position because that 
should always be stored outside die kernel. That is, the application decides where the mouse is; the kernel 
simply updates the position relative to die absolute position specified. 

'ITic kernel docs not provide any scaling of mouse movements. That is left to the application. 

31.3. Serial Line 

The kernel device server provides access to raw serial lines through the serial device. Two serial lines arc 
supported, but only one instance for each may exist at a time. 

In a create instance request, the name serialO or serial I specifics a serial line. The filemode must be 
FCREATE. The instance id returned is used for output; die instance id ■+ 1 is used for input. Parameters for 
the input instance can be obtained using Query Instance. 

Each serial line is a pair of streams, one readable and one writcablc. Characters read from each serial line 
arc buffered in the kernel until a process reads from the device, but the buffer is rather small, so a user who is 
interested in input from a serial line should keep a process "listening" to it at all times. The serial line device 
docs not provide any echoing of input characters, nor docs it convert input editing or conversion of ncwlinc 
characters to a carriage return/line feed sequence on output. 

The serial device drivers support Query File and Modify File operations to allow changing such parameters 
as the data rate, bits per character, and die suite of the modem control outputs DTR and RTS. The necessary 
message structures and constants for these operations arc defined in the standard header file <Vserial.h>. (At 
this writing, die Query and Modify operations arc not implemented in the Sun- 1 serial device driver.) 
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The kernel console device is intended to provide a measure of hardware independence to programs doing 
interactive character stream input and output. The console device provides access to the console keyboard 
and display of the workstation the kernel is running on, independent of the type of workstation. On 
workstations whose keyboards arc connected to serial line 0, reading from the console device reads from serial 
line 0; on others, it reads from the port to which die keyboard is connected. Likewise, on workstations with 
frame buffers, writing to the console device draws characters on the frame buffer; for those without, writing to 
the console sends output to serial line 0. In cases where the console uses serial line 0, instances for serial line 
and the console may not both exist at the same time. 

A create instance request must specify filcmodc FCREATE, and name console. The console device is a pair 
of streams, one readable and one writcablc. As with the serial line device, the instance id returned by a 
Crcatcinstancc is writcable, and that instance id + 1 is readable. The parameters of the second instance can 
be obtained using Quciy Instance. Both instances arc marked INTERACTIVE, but SET.PROMPT and 
SKI'JiREA K.PROCESS arc not supported. 

Console device input is buffered in the same way as serial line input (sec above). The console device does 
not provide any echoing or output conversion, but it docs make an effort to sound the workstation's beeper 
when an ASCII BEL, character is output. 

The console device is automatically opened by the kernel upon creation of the first team, and is ordinarily 
never closed. 

31.5. Null Devices 

Two null devices arc available, and arc normally configured into all versions of the V kernel. The nullin 
device is a readable stream diat returns an cnd-of-filc indication on every read attempt. The nulhui device is 
an endless sink for output. 
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Exception Server 



The exception server handles processes that have incurred a processor exception during their execution. It 
is included in programs that run directly under the V kernel by including a call to 
InitExceptionServer() at the beginning of the program. This call returns the pid of the exception 
server if successful, else 0. If an exception server already exists, In1tExc8ptionServer( ) will not start 
another. The pid of the exception server is also returned by 

GetPid(EXCEPTION_SERVER, L0CAL_PID) 
The standard V executives automatically start up an exception server. 

When a process incurs an exception, it causes a trap which is fielded by the kernel The kernel effectively 
causes the process to send a message to the exception server with the contents of die message describing the 
exception incurred. If dicrc is no exception server, die kernel disables die faulting process by causing^it to 
send to itself, which permanently blocks die process. 

The exception server checks to sec if another exception handler has registered for this process or an 
ancestor. If so, it forwards the message to the handler. For ordinary programs, arrangements arc made for 
such messages to be passed on to the V debugger (described in the V-Sysfem Commands Manual). The format 
of the exception request and registration messages arc defined in <Vcxccptions.h>. The only request types 
supported arc lv\CHFnON_RKQUl<ST and RKGISTHRJIANDLKR. The RKGLSTHRJIANDU'R 
request code Is used both for registering and dcrcgistcring handlers. RXCHl y nONJ<KQUttST messages 
should only be generated by the kernel. 

If no process was registered, the exception server prints a message on the screen indicating the type of 
exception, the pid of the faulting process, and the instruction, program counter and status register at the time 
the exception occurred., The exception server then destroys the faulting process, thus preventing it from 
doing further harm. Note: the program counter may have been incremented beyond the actual instruction 
incurring the exception so it should not be considered exact, although the error message routine attempts to 
find the correct PC by searching for the opcode of the instruction that was reported in the exception message. 

The exception server and its standard message printing routine arc included in a special V exceptions 
library. The loader may be instructed to search this library using the -Wexcept option on its command 
line. The error printing routine is available to other exception handlers as 

short *StandardExceptionHand1er(req, pid, fout) 
ExceptionRequest *req; 
Processld p1d; 
File *fout; 

where req points to the exception request message, pid is the process id of the process that incurred the 
exception, and fout is the file on which the message is to be printed. The routine returns the PC value at the 
time of the exception, corrected as described above. 
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The pipe server is an I/O server that implements a synchronized stream file called a pipe. A pipe is a 
unidirectional flow-controlled communication channel between two processes using the standard f/O 
protocol. V pipes arc similar to Unix pipes. 

A pipe file instance is type STREAM, VARIABLILBLOCK, and READABLE (for the read end) or 
WRITEA BLE (for die write end). 

In response to a CREATE J NSTANCE request, the pipe server creates an instance of a pipe, which is 
actually two file instances representing the read and write ends of the pipe. The file id returned in die reply to 
the CREATKJ NSTANCE request is the file id of the write end. The file id of the flic instance for the read 
end is one greater than the file id lor the write end. The file instances arc owned initially by the processes 
specified in the readowiicr and wriieowner fields of die CrcatcPipe Request. When a pipe is created, it is 
allocated a fixed number of buffers between 2 and 10 as specified by the buffers field of the 
CrcatcPipcRcqucst. Include <Vpipc.h> in a program to define CrcatcPipe Request. 

Pipe synchronization provides that a request to read a block Uiat has not yet been written is queued until 
that block is written. Also, a request to write a block when die current buffer limit for the pipe is exceeded is 
queued until buffer space is available. 14 A request to read from an empty pipe whose write file instance has 
been released is replied to with an END_OIM ; lhE reply code. When die read end file instance is released, 
unread dam is discarded and the data of subsequent writes to the write instance arc discarded with the write 
returning successfully. A pipe no longer exists when both the read and write instances arc released. The pipe 
server periodically checks diat die owners of both file instances of the pipe exist. When die server determines 
that the owner of an instance no longer exists, it effectively releases that instance. 

The pipe server is located by 

server.pid - GetPid(PIPE_SERVER,ANY_PID) 
where die pipe server may be local to the workstation or located on a server node. 

The pipe server can be compiled as an independent V program or included in another program. To include 
the pipe server directly in a V program, call 'the function InitP1peServer( ) at die start of the program 
and cause the linker to search die pipe server library when loading the program (i.e., add -IVpipe on the C 
compilation command line). 'Hie standard V command pipeserver may be run in die background to provide a 
local pipe server on any workstation. The V executive automatically starts up a local pipe server if there is not 
one available when a pipe is needed. 



14 Actually only one reader and one writer arc queued; the rest arc replied to with a RIH'RY reply code. 
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Internet Server 



The internet server is an I/O server that provides network communications using any of several protocols. 
It is essentially a protocol converter which allows applications which communicate by means of the V I/O 
protocol to communicate with hosts which cart only (or prefer to) be readied by some other protocol. As 
such, the server has been structured in a manner which allows easy addition and deletion of protocols as 
needed. The server consists of a general framework, which is independent of the particular protocols being 
supported, and one or more protocol-specific modules. Each module implements a particular protocol and 
must interface that protocol to the requirements and facilities provided by the server's general framework. 
Currently die DARPA Internet protocols IP and TCP, and the Xerox PUP datagram protocol arc supported. 

34.1 . Running the Internet Server 

The internet server can be compiled as an independent V program, or linked into another program. 

The standard V command "intcmctscrvcr" may be am in the background to provide a local internet server 
on any workstation. The intcmctscrvcr program by default will only register the server for die logical id 
INTERNKT.SKRVER on a local basis. Specifying the -g option to the intcrnctscrver program will cause it to 
register itsclfglobally so that it can create connections for arbitrary hosts in the V system. This facility allows 
local 'hosts to avoid spending some 10OK of memory for this server. 15 Two additional switches arc available 
with the internet server, -d turns on debugging print-outs: and -q starts up a "query" process which can be 
used to query the internal state of the server from the user's keyboard. Normal users should not need to 
concern themselves with these options; they arc intended mainly for people who arc adding additional 
protocols to the server. 

To include the internet server in another V program, have it create a process which executes the function 

InitInternetServer(qFlag, localFlag, debugFlag) 

1nt qFlag; /* Set up query process for runtime 

diagnostics if qFlag is true. */ 
int localFlag; /* True if internetserver should be local. */ 
int debugFlag; /* True if debug output should be printed. */ 

and cause the linker to search the V internet library when loading the program (i.e. add -IVintcrnct on the C 
compilation command line). It is generally preferable to am the internet server on its own team by invoking 
the intcrnctscrver program described above, rather than linking it into another program. 

34.2. Accessing the Internet Server 

Once the internet server has been started it can be accessed using the I/O protocol plus the protocol-specific 
requests and parameters specified in <Vncth>. 

A CRKATEJNSTANCK request to the internet server must specify the mode FCREATR It results in the 
creation of two instances, one of type READABLE, VARIABLKJHXXK, and STREAM, the other of type 
WRITHABLE, VARIABLEJJLOCK, and STREAM. 'Hie parameters of the writcablc instance arc returned 



["his can degrade performance however. For bursty applications such as telnet connections it usually not a problem. 
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in the CrcatcInstanceRcply. The readable instance has an instance id equal to the id of the writcablc instance 
plus I; its parameters can be obtained using QUERY JN STANCE 

An internet server connection is owned by the process which requested its creation. If that process should 
die then the connection is aborted. Ownership of a connection can be passed on to another process by means 
of the SETJNSTANCEJDWNER request 

34.3. DARPA Internet Protocol (IP) 

Possession of an IP network instance provides a process access to the network for sending and receiving IP 
packets of a specific IP protocol type. Differing IP instances are delineated by the protocol field in die IP 
packets. Any protocol id value may be specified when creating the instance except for those values already 
taken. For example, the value for TCP, is already taken by the TCP implementation inside the internet server 
itself. Creating an instance with protocol yields a "promiscuous" instance that receives all protocol types 
which have not been specified by any other active IP instances. 

IP network instances expect WRITE. INSTANCE to supply completely packaged IP packets. 
READ INSTANCE similarly will return complete IP packets. This approach allows IP instances to remain 
connectionless in concept and thus avoids the overhead of establishing a network connection instance for each 
different set of IP packet parameters. (Remember that READ and WRITE under the I/O protocol don't 
allow for specification of parameters.) 

To open an IP network instance, use CREATEJNSTANCE and specify the protocol by overlaying the 
IpParms structure definition in Vncth onto the unspecified field of the CrcatclnstanccRcquest structure. 
QUERY FILE wilt return the value of the protocol field for an IP instance. MODIFY J ; ILE has no meaning 
for thcsc'instanccs. A standard library routine, Opcnlp, is provided to allow creating an IP instance and 
allocating a File structure for it, for use with other I/O library routines. 

34.4. DARPA Transmission Control Protocol (TCP) 

TCP file instances created by the internet server implement DARPA TCP byte stream connections. There 
arc three minor differences from the specification in the DARPA Internet Handbook. First, the "push Hag" 
is always set - data written is transmitted over die network as s<x>n as possible. (Buffering of data is 
performed by the I/O library routines and would thus be redundant.) Second, the urgent data flag is not set 
as part of a write operation. Instead, a MODIKYJ-'II.E request is used to set the urgent data llag immediately 
before a write operation containing urgent data. Hie urgent data flag is reset immediately after the write 
operation arid thus must be set using a MODIFY_FII,E request before each urgent daui write operation. 
Third, Uicrc is not concept of connection timeout provided. Connections arc aborted if their owner process 
goes away. 

Two variants of CREATEJNSTANCE arc permitted on instances- of type TCP, corresponding to the 
Active and Passive opens of the Internet Handbook. Note that the foreign host must be specified completely 
when issuing a CREATEJNSTANCE request with the active bit set A standard library routine, Open Tcp, is 
provided to allow creating a TCP instance and allocating a File structure for it, for use with other I/O library 
routines. 

Two types of release mode arc supported for RELEASE J NSTANCE requests corresponding to die Close 
and Abort primitives of the DARPA specification, respectively REL.STANDARD (equal to 0, die normal 
release mode defined by the V I/O protocol) and REL.ABORT. Releasing the writcablc instance closes the 
client's end of the connection. Data can still be read from die readable instance until die other end closes. It 
is necessary to release both die readable and writcablc instances to deallocate a connection. 

Since TCP supports the concept of a byte stream, die READJNSTANCE and WRITE JNSTANCE 
operations do not segment die data flow in any way. The presence of unread urgent data in die receive buffer 
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of a TCP instance is signaled by the UrgcntData reply code to READJNSTANCE and QUERY.F1LE 
requests until the urgent data has been read by the client. Any READJNSTANCE requests outstanding 
when a TCP connection closes for whatever reason are replied to with a rcplycode indicating the reason. An 
attempt to read from a closed connection is signaled by an END_.OF.FILE reply code. 

The QUERY_FILE operation may be used on TCP instances to find out the state of the TCP'conncction. 
MODIFY FILE may be used to change various parameters of the connection. The structure TcpParmsl in 
Vncth defines the parameters which can be set both at CREATEJNSTANCE time and by means of a 
MODIFY FILE request. The meaning of the fields arc defined in the Internet handbook. TcpParms2 
defines both parameters which may be set and state variables which may not be set but whose values are 
returned if QUERY JHLE is executed with TcpParms2 specified. The parameter in TcpParms2 which may 
be set is sndUrgFlagT This parameter is used to signal urgent data. The rcvlirgFlag field returns whether or 
not urgent data has been sent from the remote host and not yet received. The bytcsAvail field indicates how 
many bytes of data are waiting to be received by the user. The state field indicates what state die connection 
is in with respect to being open, listening, established, closcd-waiting-for-remotc-ciose, etc. (sec the Internet 
handbook). 

34.5. Xerox PUP Protocol 

Possession of a PUP network instance provides a process access to die network for sending and receiving 
PUP packets on a specific local PUP port. Different PUP instances arc delineated by the local socket field in 
the PUP packets. (Net and host fields will be the same for all PUP packets received by the local host, of 
course.) Opening socket yields a "promiscuous" instance that fields all PUP packets whose local socket 
numbers have not been explicitly registered for. 

PUP network instances expect WRITEJNSTANCE to supply completely packaged PUP packets. 
READJNSTANCE similarly will return complete PUP packets. This approach allows PUP instances to 
rcmainconncetionlcss in concept, and thus avoids the overhead of establishing a network connection instance 
for each dilTcrcnt set of PUP packet parameters. 

Since PUP instances arc connectionless, MODIFY J 7 U.E has no meaning for these network instances. 
QUERY J'lLE will return the value of die local socket field for an PUP instance. (QUERYJNSTANCE will 
only return whether an instance is IP, TCP, or PUP.) 

A standard library routine, OpcnPup, is provided to allow creating a Pup instance and allocating a File 
structure for it, for use with other I/O library routines. 

34.6. Adding New Protocols 

This section should be of interest only to persons who wish to add an additional protocol to (or remove one 
from) the internet server. It describes die specifications governing the interactions between particular 
communications protocols and the general framework of the internet server. 

There arc two interfaces that a protocol must deal with: the external interface lo clients of the internet 
server, and the internal interface to die general communications facilities provided by the server's framework. 
The external interface consists of the operations, message formats, etc. that the protocol must understand in 
order to interface with a client's V I/O connection. The internal interface consists of the routines, message 
buffer conventions, etc. diat the protocol implementation must respectively use or provide in order to send 
packets to die network and receive packets from the network. 
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34.6.1. External Client Interface 

The external interface to a protocol is dictated for the most part by the V I/O protocol specification. 
Interaction between a client and the internet server is by means of a V I/O connection and the only variations 
that can be effected arc by means of the QucryFile and ModifyFilc operations. Thus clients open a 
connection by means of the Crcatclnstancc operation, they read and write data by means of the Rcadlnstancc 
and Writclnstancc operations, they determine die general suite of a connection by means of the 
Qucrylnstancc operation, and they close a connection with the Release Instance operation. 

A connection is "owned" by the client process which sent its Crcatelnstancc request, but can be transferred 
by means of a SctlnstanccOwncr request. The semantics of ownership are that a connection must be aborted 
if its owner process dies. One of the general facilities provided by the internet server is monitoring of the 
existence of connections' owners. However, the protocol implementation module is responsible for providing 
an abortion routine. 

Protocol-specific interactions are handled by means of the QucryFile and ModifyFilc operations. Protocol- 
specific instantiation parameters can also be specified as part of the Crcatclnstancc operation. The QucryFile 
operation is used by the client to determine the state of protocol-specific connection variables; the Modify File 
operation is used, to modify these variables. Thus the manner in which tilings such as the "Urgent Data 
Notification" facility in TCP must be implemented is the following: 

1. 1*hc client's Rcadlnstance operation returns an exception code indicating that something out of the 
normal has happened. 

2. The client docs a QucryFile operation to determine the protocol-specific state of the connection and 
obtains the "Urgent Data Notification" on return. 

Similarly, a client wishing to signal "Urgent Data" on a TCP connection must do so with a ModifyFilc 
operation. 16 

34.6.2. Internal Protocol Interface 

Protocol implementations must interface both to the external internet server client and also to the internal 
environment of the server itself. This internal interface consists of the following components: 

1. A network packet buffer module which all protocols must use. 'ITiis module provides a pool of packet 
buffers which have a standardized header format so that various general facilities can manipulate them. 

2. A process structure specification for the protocol. All protocol implementations must define certain 
processes and be aware of the existence of certain other processes. Part of this specification is a 
specification of the message interactions between these processes. 

3. A set of protocol-independent routines supplied by die server which all protocol implementations must 
use for such tilings as writing packets out to the network, obtaining and returning packet buffers, etc. 

4. A set of protocol-specific routines supplied by the protocol implementation which arc used by the 
general server facilities to return incoming network packets to a connection, signal timeout conditions, 
etc. 

These components will be described in more detail in the following subsections. 



16 Thc reason why the V I/O protocol specification has been structured in this manner is Tor reasons of efficiency. The vast majority of 
data read and write operations done 'on a connection arc done with "normal" settings for the connection parameters. Ity removing 
parameter specification from the read and write Derations these operations can be executed more quickly. 
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34.6.2.1. A Brief Overview Of The Internet Server's Structure 

The internet server consists of the following processes: 

1. A connection-establishment process. This process registers itself as the internet server logical id and 
waits for connection creation requests from new clients. For each new connection creation request it 
invokes a creation routine for the protocol specified in die request. This routine is responsible for 
setting up a connection and its associated data structures and handling proccss(es). 

2. Connection handling processes. Each protocol connection is handled by one or more separate 
processes. It is up to the protocol implementation to decide how to structure the connection handling 
processes for a connection. However, one of these must be designated the "primary" connection 
process. This process will be responsible for handling all communications with the rest of the internet 
server. 

3. A network reader process. The V kernel allows only one network device instance to exist at any time. 
The network reader process reads packets from the network device and calls a protocol -specific routine 
for each protocol being supported. The protocol-specific routines invoked arc responsible for 
determining which connection of their protocol type a packet should be given to. The network reader 
process runs at the highest priority allowed so that it can read and multiplex incoming network packets 
before they arc overwritten by subsequent packets in the kernel device. 

4. Two timer processes. The first timer is a timeout timer which wakes up periodically and invokes a 
timeout checking routine for each connection. If the timeout check for a connection returns a time 
which is less than the current time then, a message is sent to that connection's primary connection 
handling process. The timer determines how long to sleep before waking up again by keeping track of 
the minimum timeout time beyond the current time. The second timer checks whether any connection 
owners have died. A message is sent to the primary connection handling process of each connection 
whose owner has died signalling that the connection should be aborted. This second timer wakes up 
once every 5 seconds. 

34.6.2.2. The Packet Buffer Module 

The packet buffer module provides a set of routines which manage a pool of packet buffers which arc used 
as the medium of data transmission inside the internet server. These packet buffers are handed between 
various parts of the internet server by means of pointers (to avoid copy operations) and their header format 
must be understood by all parts of the internet server. 

The header format for packet buffers is die following: 
typedef struct pbuf 

{ 

struct pbuf *next; /* General purpose link field.*/ 

int length; /* Length of the data in the buffer. */ 

char *dataptr; /* Location of the start of the 

data. */ 

unsigned unspecif 1ed[2] ; /* Scratchpad fields. */ 

char data[MAXPBUFSIZE]; /* The actual packet buffer. */ 

} *PktBuf; 

The next field allows packet buffers to be placed in various qucucing data structures. 'Hie dataptr field points 
to the start of the data, in the data array. Packets arc typically constructed starting from the back of the data 
array, with various headers progressively added on to the front The unspecified fields arc intended for 
storing various packet-specific items of infonnation. They arc used as scratchpad working areas. 
MAXPIJUFSIZR must be large enough to accommodate all packets encountered by die internet server. It is 
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set to the maximum allowed packet size of the physical network. 17 

The routines provided by packet buffer module are the following: 
PktBuf A11ocBuf(); 

DeanocBuf(pkt); 
PktBuf pkt; 

Buffers arc handed out one at a rime by means of calls to AllocBuf(). Buffers are returned to the free pool by 
calling DcallocBuf(). These routines manipulate the buffer pool in an atomic manner; so tiiat they can be 
used from multiple processes without conflict. 

34.6.2.3. Process Interactions 

The implementation of a protocol connection must deal with the network reader and the two timer 
processes in a prescribed manner. In order for these processes to know whom to send messages to each 
connection must have a "primary" process associated with it The process ids of these primary processes are 
stored in a global data structure maintained by the internet server which contains one entry per connection. 
The details of this data structure will be described in a later subsection. 

Network Reader Interactions 

The network reader process must am at high priority and cannot afford to do much processing because it 
must always be ready to accept incoming network packets before they arc overwritten in the kernel device by 
subsequent packets. 8 This has lead to an interface format between the network reader and the various 
connection handling processes where communication is by means of atomically updated queues of packet 
buffers. 'Hie network reader process enqueues packets for a connection by calling the KnQucucSafcO routine, 
which places a packet in a specified connection queue. This routine is non-blocking (i.e. no message traffic 
involved) so that the reader process can immediately continue on to process any additional packets that may 
have arrived from the network. The connection handling processes then remove packet buffers from their 
queues by calling the DeQucucSafcO routine. The definitions for these two routines are as follows: 

EnQueueSafe(pkt, q) 
PktBuf pkt; 
RingQueue *q; 

DeQueueSafe(q) 
RingQueue *q; 

RingQueucs arc atomically updated queues which arc defined in the general internet server module. They 
must be initialized with calls to the InitSafcQucucO routine: 

In1tSafeQueue(q, MngBufs) 

RingQueue *q; /* Queue header. */ 

RlngBufRec MngBufs[]; /* An array of MAX<-RING+-BUFS queue 



records. •/ 



RingQueucs consist of the following two data types: 



17 Nolo that there is only one packet buffer size for the entire internet server. A single buiTcr size was chosen primarily for reasons of 
simplicity. Intending the packet buiTcr module to handle multiple buffer sizes would not be difficult 

18 I.e. it must be able to keep up with the (possibly many) hosts that arc sending it packets. 
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typedef struct 

{ 

RingBuf head; 
RIngBuf tail ; 
} RingQueue; 

typedef struct RingBufType 

{ 

PktBuf pkt; 

struct RingBufType *next; 
} RingBufRec, *R1ngBuf; 

The RingQueue structure defines a header record for the queue. RingBufRccs arc the actual queue elements, 
and are placed in a circular list by the InitSafcQueucO routine. 19 The pkt field of a RingBufRec is used to 
point to the packet buffer which is enqueued by it- 
Note that at most MAX- RING - BUFS packet buffers can be enqueued in a RingQueue. KnQucucSafe() 
returns if it can't enqueue a packet buffer. 

There is one caveat to the above description of how the network reader interacts with individual 
connections. The primary connection handling process for a connection may be blocked waiting on client 
requests 20 so that the packet buffer queue cannot be processed until a request message is received. To take 
care of this case each primary connection process must also set a variable indicating whether it is blocking 
awaiting client requests or not. The network reader checks this variable when enqucucing a packet for a 
connection and sends die connection a "wakeup" message if it is blocked. The process receiving the message 
must reply immediately to this message in order to minimize the time that the network reader is blocked. 

Another point to be made here is that the actions for the network reader described above (i.e. invocation of 
KnQucucSafcO and checking to sec if a "wakeup" message must be sent) arc actually part of the protocol- 
specific "network reader" routine that each protocol must supply as part of its implementation. This will be 
described in more detail later. 

Timer interactions 

The two timer processes communicate with connections by means of "timeout" messages. Whenever a 
timeout condition is detected by a timer process it sends a message to the relevant connection process 
indicating that a timeout condition has occurred. The message format employed is the following: 

struct timeoutMsg 

{ 

SystemCode requestcode; /* Standard message request code 

field. */ 
short unused; 

unsigned timeoutCondition; /* Which timeout has occurred. */ 
unsigned unusedl[6]; 

}: 
The requestcode field is the same as Unit used for all other message requests. However, instead of a 
"standard" V I/O protocol request code an internet server-specific request code signalling timeout is used. 
The timeoutCondition field specifics which timeout condition has occurred. 



The reason why a circular queue of this form is needed stems from the problem of maintaining these queues in an atomic manner. 

^fhc protocol implementations to date have consisted of a single process per connection which alternately waits on client requests 
and processes it packet buffer queue. 
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34.6.2.4. Protocol-Independent Interface Routines and Data Structures 

Global Data Structures 

There is one global data structure that must be maintained by all active connections in the internet server. 
This is the NctinstTablc, which contains an entry for each connection specifying various V I/O protocol- 
specific parameter values, the process id of the primary connection handling process, and a pointer to a 
control block associated with that connection. The V I/O protocol parameter information is used by the 
QucrylnstanceO routine for answering Query Instance requests about connections. The process id is used by 
the network reader and timer processes to find the primary process for a given connection. The control block 
pointer is used to access connection-specific information. It is intended for use by the protocol-specific 
network reader and timeout checking routines. 

The primary manner in which connections manipulate the NctinstTablc is through the following two 
routines: 

1nt AllocNetInst(prot, ownerPid, p1d, rblockslze, wblocksize, tcBId) 
1nt prot; /* Connection protocol type 

(TCP. PUP, etc.) */ 
Processld ownerPid; /* Process id of owner -of the 

connection. */ 
Processld pid; /* Process id of primary connection 

handling process. */ 
1nt rblockslze, wblocksize; /* Block sizes for resp. read and write 

V I/O connection instances. */ 
unsigned tcbld; /* Pointer to the control block for 

this connection. */ 

Deal locNet Inst (Index) 

int index; /* Index of NetlnstTable entry to 

deallocate. */ 

AHocNctfnstO returns an index into die table where die newly allocated entry has been placed. Individual 
fields can then be set by indexing through this value into die table. (K.g. SctlnstanccOwner requests would be 
dealt with in diis manner.) 

Rach protocol implementation is expected to employ these routines to manage die NctinstTablc in a correct 
manner. I.e. allocation and deallocation of NctinstTablc entries is not done automatically by the server's 
general facilities. 

Useful But Not Ksscntial Routines 

ITic internet server provides several generally useful but not essential routines which may be employed by 
protocol implementations if they so chose. 'ITicsc include the following: 



rhese requests arc actually directed at the connection handling processes themselves, implying thai each connection could employ 
its own Query Instance routine. I lowcvcr no benefit would be gained by such duplication. 



V-SYSTI-M 5.0 RI-FRRKNC1- MANUAL SliRVKRS 



PROTOCOL-INDEPENDENT INTERFACE ROUTINES AND DATA STRUCTURES 177 

SystemCode Querylnstance(rqMsg) 
QuerylnstanceRequest *rqMsg; 

Boolean Inval idFneid(rqMsg) 
IoRequest VqMsg; 

ReplyToRead(replycode, p1d, packet, bufferPtr, length) 

SystemCode replycode; /* Reply code to send to a reader. */ 
Processld pid; /* Process Id of the reader. */ 

PktBuf packet; /* Packet buffer containing data to 

return to the reader. NULL if 
there is no data to return. */ 
char *bufferPtr; /* Address of reader's buffer. */ 

int length; /* Length of data to return. */ 

QueryProcess(> 

QucryTnstanccO returns the state of a 1 specified network connection. It is V I/O protocol-specific and hence 
independent of the particular network protocol being supported by the other end of the connection. It 
obtains iLs information from die NctlnstTuhlc entry for die connection. Connections arc specified in the 
request message in the same manner as with all other V I/O connections, namely by a flleid. 

InvalidKilcidO checks whether the fileid field in a client's request message is reasonable; i.e. whether it maps 
to an existing connection entry in NctlnstTablc which is in use. All incoming client requests should be 
checked with diis routine to avoid corruption of other connections' control blocks. 

RcplyToRcadO is a generic routine for replying to a client's read request. It performs the MovcTo 
operation needed to move data from a packet buffer to the client's read buffer and packages an appropriate 
reply message. 

Query ProccssO i* a routine which runs in its own process and is used for debugging. It provides a means 
for examining and changing the state of the internet server while it is in operation. 

34.6.2.5. Protocol-Specific Interface Routines and Data Structures 

There arc two types of protocol-specific routines that a protocol implementation must provide: network- 
level routines and connection-level routines. Network-level routines arc used by die network reader process 
to multiplex incoming network packets to die correct connection. Connection-level routines are used to 
initialize a protocol, create a new connection and interface with die connection timeout checking process. 

Protocol implementations arc usually done for protocol families rather than individual protocols. For 
example, the current internet server implements both die IP and die TCP Internet protocols. However, rather 
than implementing these two protocols as separate modules, dicy arc implemented together, so that the TCP 
module can make use of facilities already defined by the IP module. This results in a situation where only the 
IP module interfaces with die network layer and die TCP module interfaces internally to die IP module. Thus 
the IP/TCP protocol family implementation has three interfaces to die rest of die internet server rather than 
four: it has a single network-level interface and a eonncclion-lcvcl interface for both IP and TCP respectively. 

Protocol-specific interface routines arc accessed by the general server facilities dirough function tables 
indexed by protocol type. There arc two such function tables, one for the network-level routines and one for 
the connection-level routines. The format of these tables is described below. 

Network- level 

The network-level function table is called PnctTablc and is defined as follows: 
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struct PnetBlock 

unsigned prot; /* Network protocol type. */ 

Boolean active; • /* True 1f a network connection is 

active for this protocol . */ 
1nt (*initNetProt() (); /• Initialization routine for this 

protocol . */ 
int (*rcv) (); /* Receiving routine for this 

protocol . */ 
} PnetTable[NumPnetProtocols]; 

The first two fields are actually not functions. The prot field is used to store the network protocol type id so 
that the network reader process can figure out which table entry to use for a given network packet. 

The active field is used to allow the network reader process to "short circuit" discarding of broadcast and 
invalid packets for inactive protocols. Without this field the reader process would have to call the rcv() 
routine for these packets since it can't tell itself whether they should be discarded. The active field is 
managed through the following two routines: 

ActivateNetProtocol (prot) 
int prot; 

DeactiveateNetProtocol (prot) 
int prot; 

prot specifics which table entry to access. 

Associated with the active field is another tabic, called NctLcvelProtocol, which is used to map from 
connection protocols to die network-level protocols which support them. For example, the IP/TCP protocol 
implementation described previously would designate both IP's and TCP's network-level protocol as being 
" IP. The definition of the table data structure, along with an example initialization is as follows: 

int NetLevelProtocol[NumProtocols] » 

0, /* IP */ 

0, /* TCP */ 

1, /* PUP */ 

}; 

'Hie index of each entry corresponds to the index of the corresponding protocol entry in the I'uttcTuhlc tabic. 
The contents of each entry is the index of the corresponding network-level protocol in the Pnct Table table. 
Thus, in die example shown, the KuncTable defines die IP protocol at index 0, die TCP protocol at index 1, 
and the PUP protocol at index 2. The Pnct Table defines die IP network-level protocol at index and the 
PUP network-level protocol at index I. 22 The initNctProt field specifics an initialization routine for the 
protocol which is called at server boot time. 

'Hie rev field specifics a routine which is called whenever a network packet arrives which has a protocol type 
equal to diat specified in the prot field of die entry (and the active field is true). This routine is responsible 
for figuring which connection of its protocol, if any, should receive die packet If a connection is found dien 
the routine is responsible for enqucucing the packet in diat connection's RingQueue (using die 
EnQucucSafcO routine) and for checking to make sure that the connection's proccss(cs) will actually be able 
to process the enqueued packet buffer. (I.e. if the connection's processes) arc reccivc-blockcd awaiting client 
requests then the routine must send a message to "wake" them up.) Packets for which no connection is found 
must be returned to die free buffer pool with a call to DcallocRuflO. 



22 Thc actual internet server code uses manifest constants instead of integers lo fill these fields • making things much more readable. 
I lowcvcr, to illustrate die principle, no manifests were employed. 
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The interface definition for the initNctProtO and rcv() routines is as follows: 
InitNetProtocol() 

Receive Pro toco !Pkts( packet) 

PktBuf packet; /* Ptr to" the incoming network . 

packet. */ 

where InitNctProtocoK) and Receive ProtocolPkts() arc example names. 
Connection-level 

The connection-level function table is called FuncTablc and is defined as follows: 
struct FuncBlock 

1nt (*InitProtocol) (); 
SystemCode (*CreateConnection) (); 
int (*NextTimeout) (); 
} FuncTable[NumProtoco1s]; 

The InitProtocol field specifics an initialization routine for the protocol which is called at server boot time. 

The CrcatcConncction field specifies a routine which is called by the connection-establishment process 
when a client requests the creation of a new connection instance. The routine must create the data and 
process structures for a new connection and then handle the Create Instance request from die client. This is 
usually also the place where a call to the ActivateNctProtocoi() routine is made to signal that the protocol is 
active. 

Hie NcxtTimcout field specifics a routine which is called by the timeout checking timer process. This 
routine returns the time of the next timeout for its connection. If that time is already past then -the timer 
process will send a timeout message to the connection's primary process. The connection's data structures are 
accessed through the tcbld field of the connection's NetlnstTablc entry. 

Hie interface definition for the InitProtocoK), Crcatc€onncctioii(), and NextTimeoutO routines is as 
follows: 

InitProt() 

CreateProtConnection(reqMsg, cl ientPid) 
CreatelnstanceRequest reqMsg; 

/* Createlnstance request message sent 
by a the client. */ 
Processld clientPid; /* Process id of the client. */ 

NextProtTimeout( tcbld) 

unsigned tcbld; /* Ptr to the control block for the 

connection. */ 

where InilProK), CrcateProlConncctionO, and NcxtProt'llmcoulO arc example names. 



23, nic method recommended for doing this is to have the routine create the connection handling processes) and then forward the 
Createlnstance request to the connection's primary process. This allows the connection handling process(cs) to manipulate their own 
data structures (which are typically kept on the processes)' stack(s)). 
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— 35 — 
V Storage Server 



The V storage server is a file system that implements the V I/O protocol. It is intended to run on a ' server 
machine with mass disk storage, thus providing file access for users on the network. It provides an alternative 
to the Unix Server for file storage. It implements a hierarchical name space with a syntax very similar to that 
of the UNIX flic system (i.e. pathname components are separated by a 7"). Additionally, there is no 
distinction between files and directories in die V storage server (i.e. any file can "act" like a directory in that it 
can have dependents in the tree structure). 

One word of caution is that the V storage server is still at an "experimental" stage, thus providing limited 
access facilities and no protection. Hence, users requiring robust file access and protcciton should use the file 
storage provided by the Unix Server. The robustness of the V storage server software is expected to greatly 
improve in die near future, 

35.1 . Running the V storage server 

One can start up the V storage server from within a V executive by typing 
storageservar 

or 

storageservar devicename 
If no device name is specified, the storage server attempts to open two devices, [dcviccldiskO and 
[device]diskl. Non-existence of a second device docs not affect correct operation of the program. Note that 
the devices must be attached to the workstation from which die command is invoked and the kernel running 
on the workstation must include the proper disk driver (sec the Kernel Section for details on which kernel 
should be booted). 

35.2. Accessing the V storage server 

When die V storage server is started it registers itself as VSTORAGE_SERVER. Thus, before a client can 
communicate with die V storage server it must do a GctPid( VSTORAG1LSERVER, ANY.PID). This 
function returns a pid to which a client will send its CREATEJNSTANCE request messages. 

A CREATE INSTANCE request causes the server to attempt to open the named file. Mies opened in 
FREAD mode'arc of type READABLE, FIXEDJ.ENGTH, and MULTl_BLOCK. The modes FCREATK 
and FMODIFY create instances of type READABLE, WRITEABLE, and MULTIJSLOCK. I- APPEND 
mode adds die further constraint of APPEND.OMLY. All instances arc random access, but operations must 
start on a block boundary. 

If the mode is FCREATE, and the file docs not exist, then a new file is created along with the associated 
instance. The permission bits of die new file will be the same as diose of its parent node in die directory tree 
structure. 

If a CREATEJNSTANCE request is successful, a file instance identifier is returned by the server that is 
used by die client for all subsequent accesses to this instance. In addition, die server returns wjlle instance 
server pid which is die process to which all subsequent I/O requests will be directed. This pid is differcni 
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than that of the main server because one process (namely, the one registered as the VSTORAGE_SERVER) 
handles CREATEJNSTANCE requests and other processes handle I/O requests. 

Once an instance has been created, a client can perform I/O operations on the file represented by the 
instance using READJNSTANCE and WRITE JN STANCE requests. These requests, if legitimate, result 
in ihQjile instance server carrying out the desired tasks. When a client is finished accessing a file, it closes the 
file by issuing a RELEASEJN STANCE request. 

The V storage server supports many other types of requests including ones to create, remove, and rename 
files and most other relevant requests associated with the V I/O and naming protocols. Note that many 
applications need not be concerned with message types and formats as actual message construction usually 
takes place within V commands and standard library routines. For example, CREATEJNSTANCE, 
READJNSTANCE, WRITE JNSTANCE, and RELEASEJNSTANCE requests are encapsulated in the 
library routines Open(), Read(J, WriteO, and Closc(), respectively. 

35.3. Creating a context for the V storage server 

In order to provide easy access to the V storage server and its directories, it is convenient to define a context 
for it using the define command. Once this is done, one can simply cd to the newly created context and 
subsequent relative path names will be interpreted relative to this context 

'1 nus, for example, 

define ss [storage] 
results in a context being defined for the V storage server, and 

cd [ss] 
causes the user's current context to be changed to its root directory. 
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Unix Server 



The V Unix server is a Unix 24 program (and not a V program or command) designed to simulate a V 
kernel/storage server on a VAX^/Unix system. It provides access to some of the Unix system services via the 
V kernel interprocess communication primitives. To workstations running the V kernel, the Unix server 
appears as a standard V server, primarily providing Unix file access using the standard V I/O protocol. 

GetPid(UNIX_SERVER , REMOTE_PID) returns the pid of a Unix server accessible to this workstation. 
With more than one, GstP1d( ) returns the pid of the first Unix server to respond to the request. This is the 
pid of a public Unix server. Public Unix servers also register themselves under the logical pid 
STORAGES ERVER. A public storage server is the definitive source for all the standard system files and 
commands whereas hosts that run non-public storage servers arc not required to be kept up-to-date. 

36.1. Sessions 

The public Unix server provides access to all files on a Unix host that are publically readable (in Unix 
terminology, "readable by others"). To get access to other files, a client must create a session with the Unix 
server. To create a session, the client sends a CREATEJNSTANCE request to the server, with the mode field 
set to.FSESSION+FCREATE. The name field of the request contains a Unix user name and password 
(separated by a NULL character). 'Hie reply message will contain the process id and instance id of the session. 
The process id allows the client to communicate directly with the session. The session provides several Unix 
system services, all running under the access privileges of the Unix user specified in the 
CREATEJNSTANCE request 

The initial owner of a session is specified by a server-specific field in the CREATEJNSTANCE request. 
The format of this request is defined in the standard header file <Vscssion.h>. 

Hie operations SEXJNSTANCEJDWNHR and RELEASEJNSTANCE arc meaningful on session 
instances. Other I/O protocol operations arc currently not supported. Releasing a session instance terminates 
the session and invalidates its process id. 

36.2. File Access 

When a CRHATFJNSTANCK request is received by the server (or session), and there arc no special mode 
Hags set (such as FSKSSION), it attempts to open the named file. As was mentioned earlier, the file must 
have others access privileges in order for it to be opened by the main server. Also, the main server docs not 
allow creation of new files, or writing to any file. A session, on the other hand, has the same access privileges 
as the Unix user that created it. 

If the client has the correct permissions, then an instance is created, with the type field set according to the 
request mode. Files opened in FREAD mode arc of type READABLE, FIXED J.ENGTH, and 
MULT1 BLOCK. Tlic modes FCREATE and FMODIFY create instances of type READABLE, 



24 
Unix Is a trademark of Bell I aboratoncs. 

v\x is a trademark of Digital Equipment Corporation. 
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WRITEABLE, and MULTl.BLOCK. F APPEND mode adds the further constraint of APPEND.ONLY. 
All instances are random access, but operations must start on a block boundary. The block size of these 
instances is equal to the maximum appended segment size for V kernel messages. 

If the mode is FCREATE, or it is FMOD1FY and the file docs not exist, then a new file is created along 
with die associated instance. Files arc created with Unix file protection bits ("mode bits") set to allow reading 
and writing by the owner, and reading by group and others. A client may change the mode bits using a 
WRITE.DESCRIPTOR or NWRITE.DESCRIPTOR request 

36.3. Program Execution 

A client can execute Unix programs through a V session by sending a CREATE. INSTANCE request with 
the FEXECUTE flag set in die mode field. The name and arguments of the program to be executed are sent 
in the segment with the NULL character being a field separator. The last argument need not be null 
terminated. The context in which die program is to be executed is also specified in the request 

Given a request the session has a built-in search path that it uses to determine which Unix program to 
execute. 26 The session tries to find the first file in a directory along the search padi that matches the given 
name. If the name contains a V, then the search path mechanism is not used and only the context specified in 
the request is searched. If the program is a shell script the Bourne shell is invoked explicitly, and it 
determines which shell should execute the script based on the normal Berkeley Unix conventions. As a 
side-effect the shell expands any wild-card characters (such as '** and T) found in the arguments. TTiis 
expansion docs not occur if die Unix program is not a shell script 

After all of the preliminary checking is done, die session forks and its child attempts to run the program. 
The parent process replies to the requestor with an OK status. However, there is no guarantee that the 
execution will be successful. A failure am occur after the OK reply has been returned, since die program is 
not loaded until the child has been forked off and the reply is sent asynchronously. If a failure of this nature 
occurs, then an error message should appear in die program's output. 

In the reply message, the session includes an instance id for the running program. If the file mode in the 
CREATEJNSTANCE request was FREAD, dicn the instance id specifies an instance of type READABLE. 
VARlABLEJiLOCK, and STREAM. 'Hie client can read die program's standard output using this instance. 

If the mode was FCREA TE, FMODIFY, or FAPPEND, then the instance returned in the reply message is 
of type WRITEABLE, VARI A BLE.BLOCK, APPEND.ONLY, and STREAM. Data written into this 
instance is piped into the program's standard input An instance with id 1 greater dian die one returned in the 
reply is also created, of type READABLE, VARIABLEJJLOCK, and STREAM. Reading from diis instance 
provides access to the program's standard output 

When the program terminates (cither normally or abnormally), the session returns an END_OF_F!LE 
reply to any write requests. Read requests will continue to be accepted as long as data is left in the pipe. 
Write requests will block if die pipe is lull and die Unix program is not reading from it (Unix pipes can 
butter up to 4096 bytes of data.) 

A client may terminate the program by releasing all instances associated with it. If only one of the instances 
is closed, dicn program will not terminate immediately. lliis allows a client to close die program's input and 
have it clean up before exiting. One should be careful not to release the readable instance before program 
termination, because Unix sends a signal to any program that writes to a pipe with only one end. The signal 
will kill the Unix process, if the process is not catching or ignoring it 



26 To find out the search pnth used' in your installation, execute the Unix command prlntenv. This will display the environment 
variables that arc passed on to programs executed via the session. 
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36.4. File Descriptors 

The server supports the V context directories and descriptor requests. One can open a Unix directory with 
the FDIRECTORY flag set in the mode field and the server will automatically translate standard Unix 
directory entries to V Unix file descriptors. Directories arc not writcable directly, but descriptors can be 
modified using a WRITE.DESCR1PTOR or NWRITKJDESCRIPrOR request. The UnixFileDescriptor 
type is defined in the system include file, <Vdirectory.h>. 

36.5. Server Name Lookup 

A client can get the pid of any Unix server by sending a LOOKUP^SERVER request to another Unix 
server. The request and reply formats arc as follows 



requestcode LOOKUP.SERVER 

hostname Pointer to the character string name of die host on which the server is running. 

namclcngth Length of the host name. 



rcplycodc Standard system reply code, 

scrvcrpid Process id of the server. 



The hostname field of the request gives the name of the host machine that the requested server is running 
on. The server's pid is returned in die serverpid field of the reply message. These message formats arc defined 
in the standard include file <Vscssion.h>. 
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Service Server 



37.1. Overview 

The service server provides a means for managing globally visible servers and services. It provides facilities 
for registering arbitrary objects (typically entries which describe the state and contact address of a server or 
service) and also for selecting a subset of these registered objects for retrieval: The selection facilities take a 
client-specified pattern and match it against the information in each registration entry to determine whether 
that entry should be included in the retrieval set 

Since any kind of object can be registered, the server is in fact a general "switchboard" service which can be 
used for arbitrary "rendevous" between two or more clients. However, the primary usage of this server is 
intended to be for management of global servers and services; and the selection facilities provided for 
retrieving registered objects have been structured with this goal in mind. 

37.2. Registering an Object 

Objects arc registered with the service server by means of the Reg1sterServer( ) library routine. This 
routine packages a registration descriptor into a message and sends it to the service server. Registration is on 
the basis of an object name and an object type. Object type essentially represents a subcontext within the 
service server and all objects of a given type must be registered using the same registration entry record 
structure. Object name distinguishes between the various registered objects within a given object type. All 
selection and listing of registered objects is done with respect to a given object type. 

The service server maintains the concept of an owner for the objects registered with it. Registered objects 
arc unregistered when their owner dies. This is achieved by having the server periodically check each 
registered object's owner's process id to sec if it is still valid. The ownership of a registered object can be 
changed using the standard SetInstanceOwner( ) library routine. 

The format of the registration entry for a particular object type is left to the client. Thus an entry can store 
arbitrary sorts of information in it However, in order to be able to perform selections of registered objects on 
the basis of information contained within their descriptors die formats of the relevant descriptor fields must 
be known to the service server's pattern matching facilities. To support this, several well-known descriptor 
formats have been defined in the C include file Vservl ce . h. These record structures arc actually descriptor 
format prefixes since the client can append arbitrary numbers of additional fields on die end of the descriptor 
structure which contain information not used in the selection process. 

There arc various well-known object types (and associated registration descriptor formats) which arc 
defined in Vservl ce, h. These arc utilized by various existing facilities such as die team servers of all hosts 
throughout the system. 

Objects can be unregistered by means of die Unreg1sterServer() library routine. Objects already 
registered can be reregistered with a new descriptor entry by simply invoking die Reg1sterServer() a 
second time. 'Hie service server will automatically remove the original entry. 

The service server has a well-known multicast group associated witii it which it uses to send out requests for 
status update when it first starts up. This allows it to reinitialize itself after crashes and other such events. The 
well-known multicast address is defined in die Venvl ron . h header file. 
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37.3. Listing Registered Objects 

All registered objects' descriptors of a given type can be listed using the standard V directory listing 
protocol. Similarly, a single registered object's descriptor can be listed using the NRcadDcscriptor request 
defined in this protocol. The format for specifying an object is 

object- type: object- name 
If no object type is specified in the Createlnstance request message then all registered objects are 
returned. 

Since the service server understands the V directory listing protocol it is possible to use the 1 1 s td1 r() and 
11stdesc() programs to query it from the exec level. Thus, for example, the status of all running hosts 
within the system can be found out by typing 

Ustdlr [service]host 
to the V exec to query the well-known object type host. 

37.4. Retrieving Sets of Registered Objects 

Sets of registered objects arc retrieved from die service server by means of a combination of service 
server-specific library routines and general V-l/O protocol library routines. The basic idea is to establish a 
connection instance, just as for a V-I/O protocol connection, through which the descriptors of the selected 
objects arc read as if they constituted a separate file unto themselves. The selection instance is created using 
the Creat8S«lect1onInstanc8( ) routine, which specifics which set of objects to retrieve. The instance 
is subsequently treated just as if it were a standard V-I/O instance; which can be read using standard library 
routines such as Read( ) and is released using the standard library routine Close( ). The only difference is 
that the first descriptor associated with the selection instance is immediately returned by the 
CraataSelectlonlnstance operation. 

Since there arc many cases where one wants only the first object returned from a set of selected objects (e.g. 
the first host from a set of hosts eligible as remote execution sites) a means is provided by which a single 
object descriptor can be retrieved without incurring the cost of establishing a selection instance. One of the 
parameters to CreateSelectlohlnstance allows one to specify whether one or more than one objects is 
to be returned. If only one is specified then no connection is . established and 

CreateSelectlonlnstance merely returns die desired descriptor record. 

Selection of objects is based on the specification of both a retrieval pattern and a pattern matching function. 
As mentioned before, all selection is done strictly within a given object typo. The pattern matching function 
to specify is determined by the format of the descriptors for the desired object type. The include file 
Vsarvlce.h contains a list of all available pattern matching functions and descriptions of the descriptor 
formats they expect to use. 'lliis include file also contains a description of the form Uiat retrieval patterns 
must take as a function of which pattern matching function is to be used. 
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The exec server is central control facility for all instances of the V system executive on a workstation. Its 
purpose is to allow sharing of code and data (such as aliases) among all executives. The intention is that while 
each executive is a separate command stream, alt executives on die same workstation should present the same 
command interface to the user. That includes customized aspects of that command interface, such as aliases. 
Since the exec server is part of the basic equipment of the V system, such customization do not vanish even if 
the terminal agent is replaced, but as long as the user is logged in. 

The exec server is located by 

Ge tPi d( EXEOSERVER , L0CAL«-PID 
It is present in all the standard configurations of the Vsystcm. 

The exec server allows programs to have instances of the executive (usually referred to simply as "execs") 
created and destroyed. An exec is known to the server by its exec id; exec ids arc small integers starting at 
O. There is currently no concept of ownership of execs-any program can destroy any exec regardless of 
whether it created it or not. 

The following requests arc supported. 

CREATE- KXECCreates an executive, with standard i/o and context specified in the request message, and 
returns the exec id. 

START- EXEC Under some circumstances an exec is not started by the CREATE- EXEC request, 
because the requestor needs to do some SctinstunccOwncr operations first. 
START- EXEC then allows the exec to start running. Normally all this is transparent and 
is handled in Creutclfacc. 

DELETE- EXEC Delete an executive. If there is a program running under it, it is abruptly stopped due to 
the death of its parent process. 

KILL- PROGRAM 

Kill the program running under an executive. If there was no program running under that 
executive, nothing happens. 

QUERY- EXEC Returns information on an executive: its status (free, loading a program, or running a 
program), its process id, and the process id of the program running under it, if any. 

CHECK -EXEC Makes a check of all executives. If the standard input server or standard output server of 
an exec has died, the exec is destroyed. This is used mainly when changing terminal 
agents. 
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Terminal agents are a generic class of scsrvcr used in the V system. A terminal agent has die duty of 
mediating between the terminal hardware, the user, and the other programs in the system, ft is responsible 
for line editing functions,c.g. the fact that the back space key does not add a backspace character to die imput 
stream but deletes a character from the imput stream. It translates die newlinc character '\n' into a carriage 
return/linefeed sequence on terminals that require it. It is also responsible for interacting with the exec server 
to create at least one executive, or providing means for the user to do so. It may, but need not, support 
multiple i/o streams. Terminal agents may differ for two reasons: because dicy arc designed to offer different 
services to die user, or because they arc designed to run on different types of terminals. 

The V system currently contains two different terminal agents, the Simple Terminal Server (sts) and the 
Virtual Graphics Terminal Server (vgts). The Simple Terminal Server is a minimal terminal agent. It 
provides a single i/o stream, using die terminal facilities provided by die firmware monitor of the workstation, 
and creates one executive using diat i/o stream. The standard V line editing interface is provided, but no 
mouse or graphics facilities arc available. The Virtual Graphics Terminal Server, in contrast, provides a very 
large set of facilities: multiple i/o streams in multiple windows, graphics, and mouse-controlled menus. But it 
supports die same line editing facilities. A large class of programs should be able to run under either of these 
terminal agents, or any odicr terminal agent, without any knowledge of which terminal agent is present. 

The newterm command allows the user to replace die terminal agent on his workstation without rebooting 
the workstation. 

39.1 . Implementation of Terminal Agents 

These are the requests that' should be supported by a terminal agent, at die minimum . It should support 
die V I/O protocal for INTKRACTIVK STRKAM flics. In simple cases, it may give polite replies to 
CRKATH- INSTANCE and RKLKASK-INSTANCKl without really doing anything, as the sts docs. It 
should also support the MODIFY — FILK request in the fashion expected by Modify Pad: it sets the pad 
mode, with a combination of hits controlling such features as line editing, echoing of input and translation of 
\n to carriagc-rcturn/lincfccd. In particular,IY1odifyPad(filc,0) should turn off all such features, giving the 
client access to die raw, unadorned terminal. 

The following conventions should be observed, in order to allow die newtenn command to work: Upon 
starting up, a terminal agent should define die context [screen] with itself as the server. It should also support 
die GctRawIO request message, in which die terminal agent tells die client the server and instance id's for its 
own standard input and output. Presumably dicsc refer to die raw terminal. 
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The Virtual Graphics Terminal Service (VGTS) allows the display of structured graphical objects on a 
workstation running the V system. This chapter describes the internal structure of the VGTS. The SDfr 
manager was originally written by "Rocky" Rhodes, incorporated into the Yale program by Tom Davis, and 
converted to use the V kernel by Marvin Thcimcr. The current VGTS is die work of Bill Nowicki. 

40.1. Current VGTS Versions 

There arc currently two working versions of the VGTS. sunlOOvgts is used on workstations with SMI 
model 100 frame-buffers, while sunl20vgts is used with the SMI model 120 framebuffcr. Users usually will 
not have to concern themselves with this, since teaml-vgts (the default first team) automatically loads the 
correct version of the VGTS. Furthermore, the program vgts is a 'bootstrap' program which loads the 
correct version of the VGTS (in a new team), and then dies. Thus, "vgts" can be given as an argument to 
newterm (sec Section 4), regardless of the framebuffcr type. 

The difference in VGTS versions is important, however, when loading special first teams that have a VGTS 
already linked in. team I + sunlOOvgts] wilt run only with a SMI model 100 framebuffcr, and 
team I + sun 120vgts] only with a model 120 framebuffcr. 

40.2. VGTS Philosophy 

The central concept of the VGTS is that application programs should only have to deal with creating and 
maintaining abstract graphical objects. The details of viewing these objects arc taken care of by the VGTS. 
This is in contrast to traditional graphics systems in which users perform the operations directly on die screen, 
or on an area of the screen referred to as a viewport or window. The types of objects managed by the VGTS 
arc discussed in more detail in the VGTS chapter of the library manual. 

40.3. VGTs, Views, and Instances 

Once the VGTS client has defined some graphical objects, it also needs to provide information on which 
objects can be viewed. Kvcry VGT is an item (usually a structured symbol) that is associated with one or more 
views, that actually appear on the screen. Kach VGT can exist in zero or more views, but each view has exactly 
one VGT associated with it The "SDF Numbers'* can be thought of as separate object definition spaces, while 
the vgts arc object instance spaces. Symbol definitions arc shared between vers, but instances of symbols 
arc not, 

The VGTS lets a user view objects in any VGTs anywhere on the screen in views. Kach view has a zoom 
factor, a window on the world coordinates of some VGT, and screen coordinates which determine its viewport. 
Although the SDF client can create default views, die VGTS user can change them with the window manager, 
and create and destroy more of them. Routines for the client's manipulation of VGTs and views arc described 
in the library manual. 

The VGTS maintains an event queue for each instance, and the vers associated with the given file instance, 
luich VGT corresponds to an instance in the V I/O protocol. The mode bits of the instance give the kind of 
events that will be queued. The details of these functions arc defined in die library manual. 
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40.4, Pad Escape Sequences 

Unless otherwise noted, all escape sequences can come with or without the optional left bracket between 
the escape and the escape command character. Arguments to the escape command arc decimat character 
strings separated by a semicolon. The following subset of the ANSI standard escape sequences is decoded by 
the SUN VGTS terminal emulator: 

BELL Causes some form of audio feedback (buzzer, bell, etc.) if possible, and flashes all the views 

of the pad.. 

TAB Positions the cursor at next multiple of eight (plus one) columns, erasing characters 

between the current cursor position and the new position. 

FF Clears the pad. 

CR Returns the cursor to the first column of the current line. 

LF NewLinc - Moves the cursor down one line. If it is at the last line of the pad, all lines move 

up (scroll). 

US Cursor moves backwards one space. 

50 Shift Out - Select the G 1 character set. Currently ignored. 

51 Shift Out - Select the GO character set Currently ignored. 
NUL Null - ignored; may be used for padding. 

DEL Delete - ignored; may be used for padding. 

ESC A CursorUp - move the cursor up one line. 

ESC [/ A CursorUp - move the cursor up / lines. 

ESC B New! ,inc ~ move the cursor down, as with LF. 

ESC [/ B NewLinc -- move the cursor down die / lines. 

ESC C CursorForward - move the cursor forward, but do not overwrite the character at the 

current position. 

ESC [/ C CursorForward - move the cursor forward / character positions. 

ESC D Index - scroll the current scroll region up one line. 

ESC [/ D CursorlJackward - move the cursor backwards /character positions. 

ESC E Next Line -- move the cursor down one line, but if it is at the end of the region, scroll the 

' region up (Index). 

VSC [lie f CursorPosition -- Move the cursor to line /, column <\ The lines and columns start from die 

upper left, which is (1,1). Specifying zero or leaving an argument blank is equivalent to a 
value of 1. 'llius l«!SQf alone will "home" the cursor to the upper left. 

ESC H Ignored. Used by some terminals to set tab stops. 

ESC [he H CursorPosition - same as ESC f. 

ESC J ClcarToEOS -- clear from the current cursor position to the end of the pad. 

ESC [n J Clear - if the argument is 2, clear the entire pad. Otherwise, clear to end of pad. 
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ESC K Clear'ToEOL —clear from the cursor to the end of the current line. 

ESC L InscrtLine - insert a line at the cursor position. All the lines below and including the 

current one arc moved down. The bottom line goes away. 

ESC [n L InscrtLine - insert n lines at the cursor position. 

ESC M Rcversclndcx -- move the scroll region down one line. The top line in the scroll region 

becomes blank. 

ESC [/ M DeleteLine - delete / lines starting from the line that the cursor is on, and move all lines 

below them up. 

ESC P DclctcChar -- delete the character at the cursor position, moving all the rest of the 

characters in the line to the left one column. 

ESC [i P DclctcChar - delete / characters, starting from the one under the cursor. 

ESC @ InscrtChar - move all die characters to the right of the cursor to the right one column. A 

space appears at the cursor position. 

ESC [/ @ InscrtChar -- Insert / characters at the cursor position. 

ESC [i m If the value of the argument is non-zero, standout mode is turned on, which will mean 

characters appear in reverse video. A zero argument resets to normal video. 

ESC[/;6r Specs fics the top and bottom lines of a scroll region. This is used in the Index and 

Rcversclndcx commands. 

ESC < Enter ANSI mode. Currently it is ignored, since VGTS pads arc always in ANSI mode. 

ESC)<; Select GO character scl Currently it is ignored. 

ESC(c . Select Gl character set Currently it is ignored. 

The default size of a VGTS pad is 28 lines by 80 columns. This is to be compatible with the "sun" terminal 
type of die Stanford Unix systems. This terminal type is just a VT-100 with 28 lines, and a lew additional 
escape sequences as described above. For TOPS-20, die command term VT100 will work. On die SU-Ai 
WAITS system, the . tty sun 28 80 command can be used for display service. 

40.5. VGTS Message Interface 

'Hie use of the vgtscxec and view manager is given in the V-System Commands Manual. This chapter 
describes only the internal programmer's interface. The following requests of die I/O protocol arc supported: 

CREATHJNSTANCE 

Causes a new pad to be created. The view manager will let the user decide where to put the 
upper lell corner of die pad by changing the cursor and blocking the process until the user 
clicks die mouse. The file instances created arc READABLE, WR1TEAULE, 
VARI ABI ,E_M -OCK STREAMS. The first two unspecified fields of the message (if non- 
zero) arc die number of lines and columns in die new pad. The filename field of the 
message is used as die name of the VGT. Usually this is invoked only by die 
OpcnPad routine described in the VGTS chapter of the Library Manual. 

QUERYJNSTANCE 

Returns the standard values, the same as a Create Instance reply. 

WRITE INSTANCE ' 
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Write the bytes to the pad corresponding to the file instance. Output conversions are 
performed if the appropriate "Cooking" modes are set. 

WRITESHORTJNSTANCE • " 

Same as WRITEJNSTANCE. 

READJNSTANCE . 

Blocks until some characters are entered into the pad. If there arc any characters already in 
the event queue for this pad, they arc returned immediately. Note that since the instance is 
VAR1ABLE3LOCK, un unknown number of characters can be returned, up to the 
blocksize. 

RELEASEJNSTANCE 

The pad is deleted, along with any views of the pad, and storage is reclaimed. 

QUERY_FILE Returns the Cooking mode bits for the pad. These are defined in <Vgts.h> and described 
below. 

MODIFY.F1LE The Cooking mode bits arc set for this pad. The structure ModifyMsg describes the format 
of this message. 

SET BREAK.PROCESS 

The break process for each instance is the process which will be killed when the Kilt 
Program command is invoked from the View Manager. 

Switchlnput The given pad (from die fflcid) is selected for input This is used in the ScicctPad routine. 

MouscStatusRcqucst 

The position of the mouse is returned immediately. This will be replaced by EvcntRcqucst 
in the future. 

MouscEventRequest 

The position of the mouse is returned as soon as a significant event occurs, as defined by 
the Mouse mode bits described in the next section. This will be subsumed by 
EvcntRcqucst in the future. 

EvcntRcqucst The first item from the event queue is returned to Uic requester. If the event queue is 
empty, the requester is blocked until an event comes in for the given vgt 

40.6. Internal Organization 

The current VGTS implementation consists of the following modules: 

• Master Multiplexor. This is the only module which is operating system dependent. Upon initialization, 
the appropriate process structure is set up. ITic main loop consists of waiting for a message, dispatching 
to the appropriate routine in the other modules, and returning a reply. Synchronization problems arc 
avoided by having the data structures accessed only in one process. 

• Terminal emulator. This module interprets a byte stream as if it were an ANSI standard terminal. 
Printable characters arc added to text objects, and control and escape codes arc mapped into the proper 
SDl ; manipulations. 

• Input handler. There arc various device-dependent input handlers. For example, a single process reads 
the keyboard and sends typed characters to die multiplexor. Another reads the mouse and tracks the 
cursor. 

• SDK manipulator. This module handles requests of applications to create, destroy, and modify 
graphical objects in structured display files. These routines maintain bounding boxes for symbols, and 
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call the appropriate redrawing routines when necessary. There is a hash table to locate items given their 
client names. 

• SDF interpreter. These are the highest level redrawing operations. The structured display files arc 
visited recursively, with appropriate clipping for bounding boxes totally outside the area being redrawn. 

• Display operations. These are the graphical operations called by the SDF interpreter. They arc device 
independent, but some of the operations, like viewport clipping, are done in hardware on the IRIS 
system. 

• Drawing primitives. There is one module which implements device dependent graphics primitives. On 
the SUN workstation this is a simple interface to the RasterOp package. At this level color rectangles 
arc drawn as stipple patterns on monochromatic displays. 

• Hit detection. The structured display file is visited, but instead of actually drawing the primitives, the 
positions are checked to match the cursor's position. A list of possibly selected objects (under other 
optional constraints) is returned to the application. 

• View manager. This module provides a mode in which users can create, destroy, and modify the screen 
layout. Viewports can be moved rigidly, stretched, or squeezed. Views can be zoomed or panned, all 
without affecting the applications manipulating the represented objects. On die SUN workstation 
zooming is by powers of two, and all motions arc done in one step. On the IRIS system zooming and 
moving viewports arc smooth, continuous operations. 

• Viewport primitives. These are the routines which perform the view-changing operations, invoked by 
either an application program or the user through the view manager. 

40.6.1 . Executive Interface 

Since the V-Systcm is intended to be modular, the VGTS can be used with an executive other than the 
standard one. The VGTS module execs . c handles the Exec Control part of the view manager command. It 
starts up new executives as new processes on the same team with the calling sequence: Exec( 1 n , out , 
err, cmdln) where all of the parameters arc pointers to Files. These arc the input, output, error, and 
command input files. The -Executive then calls the functions SetVgtBanner(f Ho, banner) and 
SetBreakPracess(f He, p1d) as commands arc executed. 

40.6.2. Frame Buffer Interface 

The VGTS was intended to be ported to different graphics devices. Someday someone might actually do it, 
and then we could have some material for this section. Right now most of the device-dependent routines are 
in the draw, c file. 
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The Simple Terminal Server(STS) is a minimal terminal agent. It does not use graphics, and it takes up less 
memory than the' VGTS. Only one i/o stream is supported. A program that wants to do graphics directly on 
the SUN hardware, not mediated by the VGTS, should be run under the STS. 

The STS creates one executive. If this executive is ever destroyed, by encountering end of file or by other 
means, it will be replaced within a second or so. Such a replacement can be forced by the sequence control-t 
x. A program running under the executive can be killed by control-t k. The normal tZ and tC commands also 
work, but they can be disabled by Modify Pad requests, while the control-t sequences cannot be disabled. 



41 .1 . Input Editing Facilities 

The STS provides a superset of the input editing facilities provided by the VGTS. All ModifyPad bits that 
arc not related to the mouse work as they do under the VGTS: CR - Input, LF- Output, Echo, Lincbuft'cr, 
PagcOutput, PagcOutputKnablc, and DiscardOutpuL 

Printing characters arc inserted at the cursor. In addition, the input buffer can be edited with Emacs-style 
text-editing commands. In the following descriptions, CTRL-x means striking the Control key and the x key 
simultaneously; RSC-x means striking the Ifecapc key and then the x key. Killing an object means moving the 
object from the input buffer to the kill buffer. 

The STS supports the following text-editing commands: 



RETURN 
LINEFEED 
CTRL-a 
CTRL-b 

BACKSPACE 
LEIT ARROW 

CTRL-c 

CTRL-d 

CTRL-c 

CTRL-f 

RIGHT ARROW 

CTRL-g 

CTRL-h 



Releases the input buffer, with a ncwlinc appended, to the application. 

Same as RhTURN. 

Move cursor to beginning of die current screen line. 

Move cursor back one character. 

Same as CTRL-b. 

Same as CI'RL-b. 

Kills the Break Process, usually the command running in the current executive. 

Delete character under the cursor. 

Move cursor to the end of the current screen line. 

Move cursor forward one character. 

Same as CTRL-f. 

Abort the command. The input editor will release the input buffer, with a CTRL-g 
appended, to die application, which is responsible for detecting the Cl'RL-g and reacting 
to it. 

IDclctc the character before the cursor. 
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del Same as CTRL-h. 

CTRL-k ■ Kill Kill from the cursor to die end of tlic current line. 

CTRL-1 Re-display the input buffer. 

CTRL-n Move cursor down one screen line. 

DOWN arrow Same as CTRL-n. 

CTRL-p • Move cursor up one screen line. 

UP ARROW Same as CTRL-p. 

CTRL-q Quote next character. Control characters arc displayed as *tC. • 

CTRL-t Transpose the two characters preceding the cursor. 

CTRL-u Kill the entire input buffer. 

CTRL-w Kill from the cursor to the beginning of the current word. 

CTRL-y Move the contents of killbuffcr into the input buffer, inserting at die current cursor 

position. 

CTRL-z Causes an End of File indication to be sent to the application reading the input. This will 

terminate the Executive if no application is running. 

Insert next character with the eighth bit set Character is displayed as '\nnn\ where nnn is 
the octal representation of the character code. 

Move cursor to the beginning of the input buffer. 

Same as ESC-, . 

Move cursor to the end of the input buffer. 

Move cursor to the beginning of the current word. 

Same as ESC-b. 

Kill from the cursor to the end of the current word. 

Move cursor past the end of the current word. 

Kill from the cursor to the beginning of the current word. Same as CTRL-w. 

Same as ESC-h and CTRL-w. 

Transpose the two words preceding the cursor. 



CTRLA 

ESC-. 
HOME 
ESC-. 
ESC-b 

ESC-BACKSPACE 

ESC-d 

ESC-f 

ESC-h 

ESC-DEL 

ESC-t 



41.2. Hardware Environment 

The STS communicates with the user via the kernel console device, if die workstation has a framebuffcr, 
characters arc sent to the terminal emulator built into the workstation's PROM monitor; otherwise, characters 
arc sent through serial line to a character terminal. 

The attached terminal or terminal emulator must understand the escape sequences sent to it by die STS for 
cursor positioning. The STS currently works properly with the following terminal emulators and terminals: 

• Any PROM monitor terminal emulator diat supports ANSI standard escape sequences, e.g., the SMI 
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PROM monitor. 
• Cadlinc PROM monitor terminal emulator. 



Any character terminal that supports ANSI standard escape sequences, e.g., VT100 or Hcath-19 in 
ANSI mode. 
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Context Prefix Server 



The V-Systcm naming world is in general a forest, with each tree corresponding to a server. Although the 
naming protocol provides a way to link this forest into a single, connected graph, we do not anticipate that 
enough permanent cross-links will be set up to make the graph connected. Note that the simplest 
implementation of a cross-link requires one server to store the (servcr-pid, context-id) corresponding to a 
context on another server. Since server processes (and hence, server pids and context ids) may be relatively 
short lived compared to the objects they provide access to (e.g., files on non-volatile storage), such a simple 
implementation is not adequate for a permanent cross-link. 

As a partial solution to this problem, each workstation in the V-Systcm contains a local name server process 
as part of its V executive. The local name server maintains a directory of local aliases for (servcr-pid, 
context-id) pairs on servers of interest. 

Further, since the present V kernel device server docs not provide character string names for the devices it 
implements, die local name server also performs name mapping on behalf of the device server. The directory 
of local aliases and the directory of devices arc maintained as separate contexts within the name server. 

42.1. Name Syntax 

When a client issues a Crcatclnstancc request using the standard Open library routine, if the character 
string name begins with *[.\ the request is sent to the first process responding to a 
GetP1 d(CQNTEXT_SERVER , ANY_PID), ordinarily the context prefix server on die client's workstation. 

If the name docs not begin with a square bracket, the- Open routine will send the request to the client 
process's "current context," a (scrver-pid, context-id) pair stored in a standard place in die client's stack space 
(the "per-process area"). The context prefix server is a character string name handling server that 

participates in the naming protocol described in chapter 30, including the ADD_CQNTKXT_NAMK and 
DHLinilLCONTKXTJSAMK requests. It recognizes the character '[' as a special escape which causes the 
next component of a CSnamc (up to the next *]' character or end of string) to be interpreted in its context 
(DKFAULT..CONTKXT). Context is the directory of contexts maintained by die context prefix server, as 
mentioned above. 

The context prefix server maps die name in brackets (context name) to a (servcr-pid, context-id) pair. If the 
name consists of more than just the context name, die request is forwarded to die process designated by 
server pid with context-id placed in the name request. The context prefix server adjusts the nameindex field so 
the receiving name server docs not look at die context name. If the name consists only of a context, the 
context prefix server may handle the request itself, depending on die type of request. For example, 
"DltliniLCONTKXT.NAMK |dial)lo|" deletes "diablo" as the name of a context in the server. On the 
other handT^CRKATlUNSTANCK [diablof would be forwarded to die context "[diablo]" with die name 
reduced to a null stringfThis request could be used to read die context directory for "[diablo]". 



27 Ity "sending a request to a context," wc mean sending the request to the server specified by the (scrver-pid. context-id) pair, with the 
specified context-id placed in the request message. This procedure causes die CSnamc in the request to be interpreted in the given 
context 
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42.2. Additional Features 

The context prefix server provides a few other features which are useful in the present V-System 
environment. 

An entry in the server's context directory includes space for a type indication and some flag bits, as well as 
an associated instance id and a long word of client-defined information. Space for these is also included in 
the standard context request and context reply message structures. The only bits of the entrytype Field which 
are clicnt-scttablc arc the SESSION and LOGICAL.PID bits. The SESSION bit has no meaning to the 
context prefix server, but is used by other standard V software to flag the primary name assigned to a session 
at the time it is created. The instance id of a session is recorded in the instanceid directory field. 

The LOGICAL.PID bit indicates to the context prefix server that the given server pid is to be interpreted 
as a logical, pid in the AN Y_PID scope rather than an actual pid. Every time the server's name mapping 
algorithm passes through this entry, it will issue a Ge tP1 d ( ) request to obtain the next pid to use. 
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— 43 — 
Team Server 



43.1. Overview 

The team server loads and keeps track of teams (usually equivalent to programs - although a program may 
consist of more than one team) running on a local host It accepts requests to load teams and terminate teams, 
and implements a directory which can be read to find out information about all teams currently running. The 
team server also registers itself with the exception server as an exception handler "of last recourse." If no 
other handler registers itself for the process which incurs an exception (or its ancestors), then the team server 
will receive the exception message and will load a post-mortem debugger to handle matters from there on, 
(Sec the command debug for a description of the debugger that is used.) 

The team server resides on the "first team" on a host, i.e., it is considered to be a server which is always 
present on a host and is loaded automatically when a host's V-Systcm is booted. 

43.2. Team Loading 

Teams can be loaded from specific object code files using the library routines LoadProg(), 
ExecProg(), or RunProgram() in the V library. These package up an appropriate request to die team 
server and take care of matters such as setting up the initial arguments to a team on its stack. The team server 
only creates a new team and loads down its object code from a designated open file instance. Setting up 
parameters and setting initial execution priority and stock size is left to die team load requestor in order to 
allow control over the order of events. This is necessary for programs such as debuggers which wish to allow 
users to set breakpoints and examine the code before a team actually starts to run. 

Load requests to die team server also specify who the "owner" of a team is. Teams arc destroyed if their, 
owner process goes away (same semantics as fur processes created by other processes). Teams can optionally 
be specified to be owned by the team server itself, thus permitting them to outlive their load requestors. 

43.3. Team Termination 

Teams can terminate by cither having their root process destroyed or by sending a termination request to 
the team server (the library routine ex1 1( ) docs this). The latter form also causes die team server to destroy 
the team's root process; but in addition it allows the team server to immediately update its record of the state 
of currently running teams. The server uses a timer process to periodically query the state of all teams which 
the server thinks arc still running and remove server entries for those that have unexpectedly gone away. 

43.4. Status of Running Teams 

The standard context directory listing protocol (sec section 30.7) can be used to obtain information on all 
teams which arc currently running under Uic team server. To obtain information on a specific team only, an 
NRKAD.Dl'SCRIPTOR request can be. made. The team of interest is specified by setting the request 
message's" amtcxtid field to the team's root process id; the CSnamc in the message has no significance. 
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43.5. Remote Execution 

The implementation of the team server and team-loading library routines is such that load requests can be 
made to both local and remote team servers, thus allowing for transparent remote execution of V programs. 
In order to assure the priority of local requests the team server keeps track of the state of the local host with 
respect to things such as whether someone is logged in or not, how many applications are running, etc. This 
state is used to determine whether or not a remote load request will be accepted or not 

Currently the only state information maintained by the team server is whether or not someone has logged 
into the host Also, the current policy with respect to remote execution is to accept all requests regardless of 
the local host's state. 

The team server also interacts with the service server in order to globally register the current state of its host 
An update of the host's status is sent whenever its state changes and whenever the service server requests such 
an update (e.g. when the service server first starts up and needs to acquire the current state of all hosts in the 
system). 
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Part IV: 
Kernel 
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Kernel Overview 



The V kernel is a message- based distributed kernel that implements a program environment of many small 
processes communicating by messages. This program environment is implemented on one or more 
workstations connected by a local. network. The kernel was designed to provide an efficient, real-time process 
model on which to build sophisticated single-user systems, multi-user systems, network-accessed servers and 
dedicated real-time applications. These applications may be distributed over one or more network nodes or 
workstations.- The kernel is also designed to be reasonably portable over a large class of machines and local 
networks. 28 This manual describes the V kernel: its operations, die mechanics of using the kernel, the 
kernel internal structure, and how to maintain the kernel, namely adding kernel operations and devices. 
Kernel operations can be broadly divided into three categories: process and memory management, 
interprocess communication, and device management. The following sections of this chapter provide an 
overview of the kernel facilities and Lhcir intended use. 

44.1. Process and Memory Management 

The kernel manages memory as entities called team spaces, which correspond to an address space or context 
on the workstation. For example, on the SUN workstation a team space is a context as implemented by the 
hardware memory management. Operations arc provided for creating team spaces, querying the size of a 
team space, and setting the size of the team space. Team spaces disappear when the last process contained in 
that space is destroyed, so there is no explicit operation for destroying a team. 

A team space is entirely contained on a single workstation. On some machines, the kernel is actually part of 
the team address space but this fact is transparent to the program. For instance, on the SUN processor board, 
segments and 1 in every context arc kernel space, but protection bits arc set to prevent access except in 
supervisor mode. 

A process is a logical activity that sequentially executes instructions. Associated with each process is a 
priority, state, a team space and a stack. The process priority dictates the preference given to this process with 
respect to processor allocation. The highest priority ready process is allocated the processor. (0 is the highest 
priority.) The state is essentially the machine state of the processor lor that process. The team space is the 
area of memory to which the process has direct access. The stack is the local memory area contained in the 
team space that the process uses for local workspace, procedure linkage and return, and the like. All processes 
with the same team space arc said to be on the same team. 

The kerne! provides support for a per-process area by associating a location and value with each process. 
Whenever a process is activated, the kernel stores its per-process value in its per-process location. By 
convention, each process on a team uses the same per-process location, and each per-process value is a pointer 
to a suindard per-process data area within the process's stack space. 

Processes can be dynamically created and destroyed. When a process is created, it is assigned a unique 
process ide ntifier that is used subsequently to specify that process. Also, it is created as part of the same team 
as its creator. A process is created in die initial state of awaiting- reply from its creating process. (Sec next 
section on interprocess communication.) When a process is destroyed, all the processes created by this 



^Currently, it has only been implemented on the Motorola 68000-bnscd SUN workstations connected by J Megabit or 10 Megabit 
IilhcrneL An implementation on a VAX 11/750 is under way. 
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process arc also destroyed. 

44.2. Interprocess Communication 

Interprocess communication is provided in two forms by the kernel. First, processes may send, receive, 
reply to, and forward fixed-length synchronous messages. A process sending a message is suspended awaiting 
reply until the message it sent has been received and replied to by the receiving process. Messages are 
currently 8 full words, where a full word is defined to be the maximum of the space required for a general 
machine pointer and the space required for a "natural" machine precision integer (32 bits on the MC68000- 
bascd SUN workstation). 

Second, a process can pass access to a single segment in its team space to the recipient of its message. The 
recipient process can access this segment for reading or writing, depending on the access specified by the 
sender, while the process is awaiting reply from the recipient. By convention, the segment start address and 
size are specified by the last two words of the message by which access to the segment was given. The 
presence of a segment and its access modes arc specified in the first byte of the message. 

A process dial is blocked awaiting reply from a process that is subsequently destroyed is unblocked with an 
indication that die receiver of the message docs not exist 

44.3. Naming 

The kernel implements a low-level naming service that provides efficient access to server processes that 
implement higher level functions. A process can register its process identifier as corresponding to a particular 
logical process identifier. Processes can then query the kernel as to the process identifier corresponding to a 
specified logical process identifier. Registration of the logical to real process identifier can be specified as 
local to a workstation, remote, or both. 

44.4. Time Management 

The kernel provides operations for reading the time, setting the time, delaying for a time period, and 
unblocking a delaying process. 

44.5. Device Management 

13cviccs managed by the kernel arc currently all accessed through die device server pscudo- process inside 
the kernel. Operations arc performed by sending messages to the device server. The protocol used in these 
messages is the Vcrcx I/O protocol 29 which is described in the V-Systeui Servers Manual. 

Devices that can be controlled without special kernel support can be handled directly by processes. Special 
devices that require kernel support but do not fit the I/O model can be handled by adding new kernel 
operations. 

44.6. Initialization 

After the kernel has completed its internal initialization, it creates an initial team space and an initial 
process on this team. It assumes there is a descriptor following it in memory that describes the code and data 
segments plus the starting instruction for this initial team. Enough physical memory is assigned to the team to 



29 " Distributed I/O using an Object-Based Protocol" by David R. Chcriton, UBC Computer Science Technical report 81-1. 
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accommodate its code and data segments. 

44.7. Distributed Operation 

The kernel supports transparent communication among several workstations running the V kernel. 
Processes on different workstations may send and receive messages and access segments as though all 
processes were executing on the same machine. This mode of operation requires a high-speed local network 
connecting the workstations. Most kernel operations may be performed transparently on non-local processes. 

44.8. Application-Level Model 

Using the kernel well requires understanding the model of processes and messages that the kernel provides, 
and how they are intended to be used. Processes represent logical activities in the application. They are 
intended to be sufficiently inexpensive to allow the use of multiple processes to achieve die desired tcvel of 
concurrency in the application. Hie process identifier is intended to serve as a loose form of capability or 
"ticket." Possession of a process identifier is sufficient to allow the process to send a message to the specified 
process. Also, because there is no notification facility on the destruction of a process, resources allocated to a 
process should be associated with its process identifier if Lhcy arc to be reclaimed. The application can then 
use "lazy reclamation" of resources by "garbage collecting" resources associated with invalid process 
identifiers. However, a process may block until another is destroyed using eidier RcccivcSpecific or Send. 

The synchronous message sending is intended to implement communication between processes that looks 
to the sender essentially like procedure calls. That is, the Send request message sends the parameters of the 
procedure and the reply message returns the results. 'Hie greater flexibility provided to the receiver allows 
sophisticated scheduling of message handling and replies, lkcausc message sending is totally synchronous, 
concurrency must be achieved by multiple processes. 

The segment access operations follow the procedure paradigm in being used primarily to access what are 
logically "call-by-rcfcrcncc" parameters. The argument for providing exactly one segment is that at least one 
is needed, and one is sufficient for die dominant activity, namely file access. It is expensive and difficult to 
provide arbitrarily many segments - having just one segment allows a simpler and more efficient 
implementation. Finally, multiple segments can be linearized to one, so no functionality is lost with this 
restriction. 

'ITicrc is no form of asynchronous communication between processes. It is intended that process destruction 
be used for asynchronously interrupting the activity of a process. 

Teams arc intended to provide fine-grain sharing of code and inexpensive sharing of data between 
cooperating processes. They separate the idea of program, executable unit, and address space from diat of 
process. 
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Kernel Operations 



The operations provided by the V kernel can be divided into three classes: kernel traps, kernel process 
operations, and kernel device operations. 

The most basic kernel operations, including Sen<J( ), are implemented as kernel traps. These operations 
arc invoked by executing a trap or system call instruction which invokes the kernel. A number of secondary 
operations are implemented by a pscudo- process running in the kernel, called the kernel process. Such 
operations arc invoked by sending to the kernel process's pid. Finally, operations on kernel-implemented 
devices arc provided by a second pseudo-process, called the kernel device server. Such operations are 
invoked by sending messages to die device server's pid, using the standard V-Systcm I/O protocol. 

The kernel traps include: 

Forward() GetPid() MoveFrom() 

MoveTo() ReceiveSpecif ic() ReceiveWithSegment( ) 

Rep1yWithSegment() . RereadMsg() Send() 

The kernel process operations include: 

CreateProcess() CreateTeam() DeTay() 

DestroyProcess() GetTime() QueryProcessState( ) 

SetPid() SetTeamPriorityO SetTeamSize( ) 

SetTime() Wakeup( ) WriteProcessState( ) 

These functions arc documented fully in the V-Syslem Program Environment Manual. Other kernel 
operations described there, such as Rece1ve(), Rap1y( ), Val 1dP1d(), etc., arc implemented as library 
functions using the basic operations listed above. 
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Exceptions and Kernel Exception Handling 



The V kernel handles exceptions (such as illegal instruction or bus error traps) by forcing the erroneous 
process to send a message to die exception server containing the details of the error. The exception server is a 
process that has registered as the EXCEPTION.SIiRVER with the kernel using SctPid. If no exception 
server exists, the message is sent back to the process that caused the error, blocking it permanently. In either 
case, other processes in the system can continue to run. 

The message from the exception-incurring process to the exception server appears as a normal message and 
can be received by the standard message primitives. After receiving the message, the exception server can 
read the faulting process's state using cither the kernel primitive QucryProccssStatc or the library function 
RcadProecssStatc. In die Sun implementation of the kernel, the registers in the suite record reflect the 
processor state at the time of the exception, unless it occurred while running in the kernel. In that case, the 
program counter and status register returned arc those that, were saved at the time the kernel trap was taken. 
The other registers reflect die state at the time of the exception. The correct program counter and status 
register contents can always be obtained from the exception message. 

The message also provides read and write access to die segment consisting of die entire team address space 
of the exception-incurring process. This provides debuggers and exception servers with complete access to 
the code and data of the process. 

The format of the exception message is given by die ExccptionMcssagc struct in <Vcxccptions.h> together 
with manifest constant definitions for die type of exception. The message format for the Motorola 68000 is 
given below. 



rcqucstcodc EXO'l'riON.REQUKST 

type Type of exception. This is encoded as the address of the MC68000 exception vector that 

was taken. 

buscrrortypc Additional information on die cause of the error, if type is equal to HUSJ-'RROR. 

code In the case of address errors and bus errors, this contains a code returned by die processor 

to identify the type of memory reference diat caused die exception. Only the low order 5 
bits of this word arc valid; the others should be masked off. For other types of exceptions, 
this word contains zero. 

accaddr The access address in the case of address or bus errors, otherwise zero. 

instruction The instruction register in the case of address or bus errors, otherwise zero. This should be 

the first word of the instruction dial caused the error. 

status The status register. 

crrpc The program counter. 

segment Starting address of die team's address space. Currently at 0x10000 on die SUN workstation 

because the kernel uses the first two segments. 

segmentsize Number of bytes in die team's address space. 
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Sec die Motorola MC68000 User's Manual for a description of the types of exceptions possible and the 
meaning of the information returned by the processor and passed on in these exception messages. 

Exceptions arc always blamed on the currently active process, even if they occur inside the kernel. For 
instance, it is possible for an exception inside the kernel to be caused by an invalid pointer passed by a process 
when invoking a kernel operation. However, it is also possible for exceptions to be caused by bugs in the 
kernel itself, though diis is unlikely unless an experimental version of the kernel is being tested. A 

standard exception server process has been implemented and is described in die V-System Servers Manual. 



Hie worst case is when the exception is caused by a bug in a kernel interrupt, handler, since in lhat case there would be no relation 
between the currently active process and the code dial caused the exception; however, in this case, the bug is likely to crash the processor 
anyway. 
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Performance 



Two measures of performance for the kernel arc die speed of various operations and space requirements. 
For a detailed account of the performance of the V kernel, we refer the reader to The Distributed V Kernel 
and Its Performance on Diskless Workstations, by David R. Chcriton and Willy Zwaencpocl, in Proceedings 
of the 9th Symposium on Operating System Principles, October 1983 (also available as Technical Report 
STAN-CS-83-973, Computer Science Department, Stanford University). 

47.1 . Space Requirements 

Hie space requirements arc dependent on the machine, the number and complexity of devices supported, 
and the maximum number of processes, teams and devices configured. Table 47-1 gives the code segment 
size for the kernel configured to support distributed operation on the SUN workstation with support for 
console device, serial interfaces, Rthcrnct interface and a mouse pointing device. The tabic also gives the unit 
space cost of a process descriptor and a team descriptor, and the total space requirements for a kernel 
configured with a maximum of 64 processes, 16 teams and 16 device descriptors. All measurements arc given 
in bytes. 

Table 47*1: SUN Workstation Kernel Memory Requirements 

Component Size in bvtcs 
code segment 31836 

process descriptor 202 

team descriptor 18 

device descriptor 44 

• total 47990 

47.2. Kernel Operation Times 

Table 47-2 gives the times for various sequences of kernel operations on the SUN workstation using a 10 
Megahertz. Motorola 68000 processor. The times for sequences of operations arc given instead of times for 
individual operations to give a better indication of the kernel overhead for higher-level operations. Kor 
instance, die Scnd-Rcccivc-MovcFrom-Rcply sequence is indicative of the time to perform a file read 
operation using the I/O protocol. These sequences arc also easier to time in some cases dian individual 
component operations. 

Table 47-2: SUN Workstation Times for Kernel Operations (in milliseconds) 
local remote 



GctTimc 0.06 Not Applicable 

Send-Rcccive-Rcply(0 bytes) 0.77 2.54 

Scnd-Rcccivc-Rcpiy(512 bytes) 1.31 5.56 

The table is not intended to be complete but simply indicative of performance. The Scnd-Rcccivc-Rcply time 
is indicative of the interprocess communication time using the kernel. The column labeled "remote" gives the 
Scnd-Rcccivc-Rcply time between two processes resident on different workstations. The GctTimc lime is 
indicative of the cost of a trivial kernel operation. All other kernel operations can be expected to be faster 
than the Scnd-Rcccivc-Rcply sequence. 
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Another measure of interest is the speed at which packets can be read and written over the Ethernet with 
the overhead of sending read and write requests to the kernel device server to access the network. Table 
47-3 gives performance figures for the kernel running on the SUN workstation connected to a 3 Megabit 
Ethernet. 

Tabic 47-3: SUN Workstation Ethernet Output 

Packet Size in bvtcs Packets ncr sec Throughput in Kbvtcs/scc 

35 
180 
170 

Similar throughput figures for a stand-alone Alto arc 4, 120 and 140 Kbytes per sec (approximately). 

On the input side, with one SUN writing as fast as possible to another, 10000 packets of 1024 bytes can be 
received in 5,89 seconds with packets lost, yielding a throughput of about 170 Kbytes per second, which is 
about 40% of the bandwidth of the net. However, for some unknown reason, packets arc dropped as the 
packet size becomes smaller. 

47.3. Interrupt Disable Time 

The interrupt disable time for the kernel is- essentially the maximum of the time required to insert a record 
in a ordered queue (the ready queue) and the time to load the processor with the state of a new process. 
Although the former is dependent on die maximum number of ready processes, it is typically very small. For 
example, on the SUN workstation, adding a lowest priority process to the ready queue when 32 processes are 
ready to execute is estimated to result in an interrupt disable time of 164 microseconds. Under normal 
circumstances, an interrupt disable time of about 30 microseconds can be expected. 
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Kernel Internal Structure 



The kernel is implemented as a simple monitor. It executes logically in its own address space in supervisor 
mode with its own code, data and stack. It is invoked by trap operations and interrupts. When a process 
executes a kernel operation or an interrupt trap is taken, the kernel executes on the kernel stack. 

48.1. Teams 

Each team is represented by a team descriptor record (TD) that describes the team space, records the root 
process of the team, user associated with the team, team priority level, etc. A machine-dependent portion of 
the team descriptor describes the team's memory space. 

48.2. Processes 

For each process, the kernel maintains a process descriptor record (PD) that contains the process state and 
sundry information about the process. When a process is running, a variable Active points at the process 
descriptor of the currently active process. 

48.3. Kernel Synchronization 

The kernel is synchronized internally by a combination of scheduling conventions and interrupt 
masking. The conventions arc: 

• Both kernel trap-invoked and intcrmpt-invoked operations only add or remove processes from the list 
of ready processes, 'llicy cannot block a process in the middle of a kernel operation. The clock 
interrupt routine that may change the state of a process blocked on a remote or nonexistent process only 
does so if it did not interrupt a kernel operation. Similarly, cthcrnct interrupts arc disabled during the 
execution of a kernel operation to prevent remote intcrkcrncl packets from interfering with the 
execution of the kernel operation. 

• A process switch occurs at the end of a kernel operation if the active or invoking process is no longer the 
highest priority ready process. The process switch occurs at the point of return from the kernel trap 
handler after executing the kernel trap. 

• A process switch occurs at the end of the execution of an interrupt service routine if the active process is 
no longer the highest priority ready process AND the interrupt servicing did not interrupt a kernel 
operation. That is. a process switch cannot occur in the middle of a kernel operation due to an interrupt 
even though the interrupt can otherwise be serviced. 

The net result is that a process executes a kernel operation indivisible with respect to other processes until it 
blocks. However, the highest priority ready process is allocated the processor whenever the processor is not in 
supervisor state. Masking of interrupts is used at crucial points in manipulation of die ready queues and 
process switching so that interrupt routines do not interfere. 
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48.4. Interrupt Routines 

Interrupts arc handled by first invoking a simple assembly language routine that saves some registers and 
then calls a C procedure associated with that interrupt level, possibly passing some arguments. A macro 
"Call inthandlcr" generates die required assembly language routines that call the C procedure it is passed as 
an argument. Interrupt- invoked routines are assumed to be short and do little in interacting with processes 
other than possibly readying a process. 

48.5. Kernel Traps 

An assembly-language module handles trap instructions, invoking the specified kernel operation and 
handling the return. On a trap, it moves the arguments onto the kernel stack and calls the specified kernel 
operation as a C function. On return, it moves the return value back to the process's stack if necessary and 
checks for a higher priority ready process. If there is one, it switches to the highest priority process. If the 
active process is still the highest priority ready process, the active process is allowed to continue execution at 
the instruction after the trap instruction in its code segment 

48.6. Kernel Process 

If the specified pid fails to validate on a Send, the Send routine checks whether it is die pid of the kernel 
process or of the device server process. If the kernel process pid was specified. Send calls the ScndKernel 
routine to perform die requested operation. Thus, die "kernel process" code is executed by the process 
invoking the operation, not a separate process running in the kernel. The message format and the request 
codes die kernel process supports can be found in <VcnvironJi>. The kernel process identifier is a global 
variable, KcrncLProccss.Pid, set at the beginning of each team's execution. 

48.7. Device Server Process 

A Send to die device server process results in Send calling the ScndDcvicc routine to perform the requested 
operation. Thus, the device server code is executed by the process invoking the operation, not a separate 
process running in the kernel. A process diat is forwarded to the device server has its finish-up function (sec 
below) set to ScndlDcvicc, and is readied, so that it will begin executing in ScndDcvicc as soon as it reaches 
die head of- the ready queue; 

48.8. Process Switching 

All process switches occur in the macro function Switch that switches from the currently active process to 
the process at die head of the ready queue. Kach process is created with its state initialized to start it at the 
initial program counter in its team space when it is readied. Switch relics on there always being a ready 
process to execute (i.e. non-empty ready queue). This is guaranteed by the presence of an "idle" process that 
is always ready and executes the processor stop or idle instruction. 

Interrupt- invoked routines execute as "involuntary" asynchronous function calls made by die currently 
active process and dius can also use Switch. 

Process switches always occur upon exit from the kernel, never in the middle of a kernel routine. Thus, the 
kernel only requires one stack, not a separate kernel stack for each process. If there will still be some work to 
be done on a kernel operation when a process is unblocked, die kernel routine that blocks it sets the finish- up 
function field in die process's state record. If this field is non-/.cro when a process is unblocked, the specified' 
function is called before die process exits die kernel. A finish-up function can block die process again and set 
another finish-up function if necessary. 
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Note: The kernel implementation described so far should support a number of different types of kernels. 
Also, this basis of trap and interrupt handling plus process switching, device management, and memory 
management represents most of the- machine-dependent code in the kernel. 

48.9. Processor Allocation 

The strict priority-based processor allocation is implemented efficiently by maintaining a queue of ready 
processes in order of priority, highest priority first. A state field in the process descriptor indicates the process 
is ready (and thus in tliis list) or else the state in which it is blocked. Process switching incorporating this 
priority-based allocation and ready queue management is implemented by two (internal) primitives. 

Rcmovcrcady(pd) Remove the specified process from the ready queue. The active process continues to 
execute until it exits the kernel even if it has just removed itself from the ready queue. 

Addready(pd) Add the specified process (descriptor) to the ready queue in order of priority, after all 
processes of die same priority as tliis process. 

48.10. Process Creation and Destruction 

Unused process descriptors arc maintained in a queue. When a process is created, a process descriptor is 
removed from the queue, assigned a process identifier, and initialized to the specified priority, awaiting reply 
suite, creator's team, etc. 

When a process is destroyed, it is removed from any system queues, such as the ready queue or any message 
queues (one major use of the PD state field is indicating presence in a queue), the process identifier is 
invalidated and all its descendants arc destroyed similarly. The resulting free process descriptors arc added to 
the end of the queue of unused process descriptors. The clock interrupt routine is charged with checking for 
processes blocked on non-existent processes (one per clock interrupt) so the process destruction mechanism 
need not worry about this. 

48.1 1 . Message Primitives 

While a message implementation normally requires independent kernel message buffers, the semantics of 
the message primitives in this kernel allow the message buffer to be statically associated with the process 
descriptor so we include it as part of the same C struct. Thus, a message is queued at a receiver by queuing 
the process descriptor of the sender, saving on extra space for sender identifier, etc. plus time to map to the 
PD of die sender for unblocking it. 

Sending to the kernel device server or to the kernel process is handled by checking die pid of Send to sec if 
it specifics die kernel device server or the kernel process when Uic pid fails to validate as a real process. The 
ScndDcvicc or ScndKcrncl routine is then called directly to implement the kernel device server or kernel 
process. 

48.1 2. Time Primitives 

Processes delaying using Delay arc maintained in a queue starting at Dclayqjicad ordered by increasing 
time to unblock. The time before a process unblocks is stored in its blockcd_on field in terms of the number 
of clock interrupts it must delay after the process before it in the queue is unblocked. 
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48.13. Distributed Operation 

The process identifier contains an indication of the host in its 16 high-order bits. When an operation is 
invoked that specifies a process identifier that fails to validate locally, it is assumed to be a remote process. 
The operation then invokes a "nonlocal" version of the operation that formats a network message and 
transmits it to the workstation host specified by the process identifier. The primary interface to the network is 
the WritcKcrnclPackct routine. 

In the case of GctPid, a message is broadcast requesting the logical id to pid mapping. 

When a process is blocked sending to a remote process, the message is retransmitted periodically by the 
clock interrupt routine until a reply is received. Hie Send fails after some number of retransmissions if no 
"breath of life" packets have been received from the remote host in that time. 

A message received on a workstation from a remote process causes a process descriptor to be allocated to 
store the message and make it appear as a local message to the rest of the kernel. A process descriptor used in 
this fashion is called an alien. Aliens arc destroyed an appropriate time interval after the Reply message is 
sent. (This interval is for idempotcnt requests.) 

This description is far from complete. For a fully detailed discussion of the interkcrncl protocol sec The 
Distributed V Kernel and Its Performance on Diskless Workstations, by David R. Chcnton and Willy 
Zwacncpocl in Proceedings of the 9th Symposium on Operating System Principles, October 1983 (also 
available as Technical Report STAN-CS-83-973, Computer Science Department, Stanford University). 
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— 49 — 
Kernel Modification and Maintenance 



The type of kernel modifications anticipated include: changing the maximum number of processes, teams, 
or devices allowed, adding or removing kernel operations, and adding support for new devices. 

49.1. Kernel Configuration Parameters 

The machine-dependent file configJi contains the kernel configuration parameters. 

MAX_PROCESSES 

Maximum number of processes, which must be a power of 2. 

MAX JTKAMS Max. number of teams, currently at most 16 on die SUN workstation. 

MAX.DBVICHS Max., number of device instances, which must be a power of 2. 

ROOT.PRiORlTY 

Priority of root process of first team. 

IN IT.STACK Size of in itial stack for root process of first team. 

ITic kernel can be reconfigured with respect to these parameters by changing their definitions in configJi 
within die constraints mentioned above and recompiling the kernel. 

49.2. Adding New Device Support 

Supporting a new device using the kernel device manager requires writing device-specific initialization, 
read, write, release, modify and intcrrupt-handling routines and adding an entry for the device in the 
DcviccCrcationTable defined in confine. There is normally a header file for the new device that defines its 
device type for this tabic plus other device-specific information required by users oftlic device. The existing 
devices and kernel operations are useful models from which to work. 

49.3. Adding Kernel Operations 

Adding a kernel operation requires writing the C routines that implement the operation, adding an entry 
for it to the kernel trap table, kcmclops, defined in trup.c and possibly adding a stub for this call to the C 
environment library for the kernel calls. Adding a new operation to the kernel process requires defining a 
new request code in <Venviron.h>, handling this request code in the main loop of the kernel process and 
writing the appropriate code for handling the request. Operations that must be available to remote processes 
should be implemented as kernel process operations rather than kernel traps. 

Certain restrictions apply to kernel operations. They may not execute trap operations or call upon services 
provided by other processes outside the kernel. However, they can use other routines already available inside 
the kernel. Kernel operations arc passed exactly 5 arguments and allow one return value. A kernel operation 
cannot take a variable number of arguments unless the number is encoded in the values passed. Operations 
that access any data modified by interrupt-invoked routines need to mask interrupts if there is any possibility 
of interference. Finally, operations that block or unblock processes should use the internal primitives 
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Addrcady and Rcmovcready. 
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— Appendix A — 
C Programming Style 



There has been an effort to use a consistent style in V for writing C programs. The style and the uniformity 
it encourages arc motivated by the desire for readability and maintainability of software. Although style is to 
a large extent a matter of individual taste, the following describes some general practices with which most of 
us agree. 

A. 1. General Format 

Recognizing that software is written to be read by other programmers and only incidentally by compilers, 
the general format follows principles established in formatting general English documents. Take a few more 
seconds to make tilings more readable; it is time well spent 

First, software is written to be printed on standard size (8 by 11) paper. This means avoiding lines longer 
than about 80 columns. In general, there is one statement or declaration per line. 

As with other documents, judicious use of white space with short lines and blank lines is encouraged. In 
particular, 

1. At least 2 blank lines between individual procedures. 

2. Blank lines surround "large" comments. 

3. Blank lines around any group of statements. 

4. Blank lines around cases of a switch statement. 

A. 2. Names 

Names arc chosen when possible to indicate their semantics and to read well in use, for example: 
if ( GetOevice(Etherlnstanee) « NULL ) return( NOTJOUND ); 

Words should be spelled out, not shortened. A good test is to read your code aloud. You should be able to 
communicate it over a telephone easily, without resorting to spelling out abbreviations. 

In addition, character case conventions arc used to improve readability and suggest the scope and type of 
the name. Global variables, procedures, strucLs, unions, typedefs, and macros all begin with a capital letter, 
and arc logically capitalized thereafter (e.g. MalnHashTable). A global variable is one defined outside a 
procedure, even though it may not be exported from the lilc, or an external variable. The motivation for 
treating macros in this way is that they may then be changed to procedure calls without renaming. 

Manifest constants cither follow die above convention (since they arc essentially macros with no 
parameters) or else arc fully capitalized with use of die underscore to separate components of the name. E.g. 
WR1TEJNSTANCE. 

Local variables begin with a lower-case letter, but arc cither logically capitalized thereafter (e.g. bl tW1 dth, 
power, maxSumOf Squares) or else totally lower case. Fields within structures or unions arc treated in this 
manner also. 
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Local variables of limited scope arc often declared as register, if they arc used very often inside inner loops. 
It is not only more efficient, but usually more readable, to put a pointer to an array of complicated structures 
(a common occurrence in object-oriented' programming) into a register variable with a short name. For 
example, 

register struct Descriptor *p ■ DescriptorTable+objectlndex; 

p->count ■ 0; 

Initial ize(p->start) ; 

p->usage * p->default; 

p->length - p->end - p->start; 

instead of the inefficient and cluttered: 

DescrlptorTableCobjectlndex]. count ■ 0; 
Initial ize( (Descriptor Tab leCobject Index], start); 

DescrlptorTableCobjectlndex]. usage - Descr i ptor Tab leCobject Index], default; 
DescrlptorTableCobjectlndex]. length - DescrlptorTableCobjectlndex]. end 
- DescrlptorTableCobjectlndex]. start; 

A.3. Comments 

There arc generally two types of comments: block-style comments, and on-thc-linc comments or remarks. 
Multi-line, block-style comments have the /* and */ appearing on lines by themselves, and the body of the 
comment starting with a properly aligned *.■ The comment should usually be surrounded by blank lines as 
well. Thus it is easy to add/delete first and last lines, and it is easier to detect the common error of omitting 
the */ and thus including all code up to and including the next */ in a comment 

/• 

• this 1s the first line of a mult1-l1ne comment, 

• this is another line 

• the last line of text 
*/ 

On-line comments or remarks arc used to detail declarations, to explain single lines of code, and for brief 
(i.e. one line) block-style descriptive comments. 

Procedures arc preceded by block-style comments, explaining their (abstract) function in terms of their 
parameters, results, and side effects. Note that the parameter declarations arc indented, not flushed left. 

SystemCode EnetCheckRequest( req ) 
register loRequest *req; 

{ 

/* 
• Check that the read or write request has a legitimate buffer, etc. 

•/ 
register unsigned count; 
register SystemCode r; 

/* Check length •/ 
count ■ req->bytecount; 
if( count <- I0_MS6_BUFFER ) return( OK ); 

req->bytecount - 0; /* To be left zero If a check fails •/ 

1f( count > ENET_MAXJ>ACKET ) 

{ 

r • BAD BYTE.COUNT; 

> 
else 

{ 

/* 

* Make sure data pointer 1s valid. 

* Check that on a word boundary and not in the kernel area. 
•/ 
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if( (IChflckUserPointer(req->bufferPointer)) || 

(Active->team->teamSpace.size < (req->buffarPointer + count)) || 
((int.) req->bufferPointer) & 1 ) 

{ 

r - HAD BUFFER; 

> 
else 

C 

req->bytecount ■ count; 

r - OK; 
} 
) 
peturn( r ); 

} 

A. 4. Indenting 

The above example shows many of the indenting rules. Braces ( "{" and "}" ) appear alone on a line, and 
arc indented two spaces from the statement they arc. to contain. ITic body is indented two more spaces from 
the braces (for a total of four spaces), el se's and else it's line up with their dominating if statement (to 
avoid marching off to die right, and to reflect the semantics of the statement), 

if ( (x • y) « ) 

{ 

flag - 1; 

printf(" the value was zero "); 

} 
else if ( y ■" 1. ) 

C 

switch ( today ) 

C 

case Thursday: 
flag - 2; 
ThursdayAction(); 
break; 

case Friday: 

flag - 3; . 

FridayAction(); 

break; 

default: 

OtherOayAction(); 

> 
} 
else 

printf(" y had the wrong value "); 

A. 5. File Contents 

Kile contents arc arranged as follows. 

1. initial descriptive comment (sec example below) contains brief descriptive abstract of contents. Some 
programmers add one or more of the following as well: 

a, a list of all defined procedures in their defined order, or alphabetically. 

b. list of recent and major modifications in reverse chronological order with indication (initials) of 
who made the change. 

2. included files (use relative path names whenever possible) 
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3. external definitions (imports and exports) 

4. external and forward function declarations 

5. constant dcclaradons 

6. macro definitions 

7. type definitions 

8. global variable declarations (use static declarations whenever possible, and group variables with the 
functions that use them) 

9. procedure and function definitions 

Here is the beginning of a file as an example. 

/• 

* Distributed V Kernel - Copyright (c) 1982 by David Cheriton, Willy Zwaenepoel 

• Kernel Ethernet driver 
*/ 

^include ". ./. ./I ibc/include/Vethernet.h" 
^include "interrupt. h" 
^include "ethernet.h" 
^include "ikc.h" 
^include ". ./mi/dm. h" 

/* Imports */ 
extern Process •Map_pid(); 
extern SystemCode NotSupported(); 
extern Devicelnstance *GetDevice( ) ; 

/• Exports V 

extern SystemCode EnetCreate() ; 

extern SystemCode EnetRead(); 

extern SystemCode E»etWrite( ) ; 

extern SystemCode EnetQuery(); 

extern SystemCode EnetCheckRequest() ; 

extern SystemCode EnetReadPacket(); 

extern SystemCode EnetPowerup( ) ; 



unsigned 

Instancel 

int 

short 

int 

int 

int 

int 

int 

int 

int 

char 

kPacket 



char EnetHostNumber; 
d Ethernetlnstance; 

EnetReceiveMask; 

EnetStatus; 

EnetFIFOempty: 

EnetCollisions ■ 0; 

EnetOverflows ■ 0: 

EnetCRCerrors ■ 0; 

EnetSyncErrors - 0; 

EnetTimeouts ■ 0; 

EnetValidPackets « 0; 

kPacke tArea[WOROS..PER J 



/* physical ethernet address */ 

/* Instance id for Ethernet */ 

/* addresses to listen for •/ 

/* Current status settings •/ 

/• FIFO was emptied by last read */ 

/• Number of collision errors */ 

/* Queue overflow errors •/ 

/• Packets with bad CRC's */ 

/* Receiver out of sync */ 

/* Transmitter timeouts */ 



PACKET*BYTES J'ERJrfORO+ZQ] ; 

/• Save area for kernel packets •/' 
•kPacketSave ■ (kPacket •) kPaclcetArea: 

/* Pointer to kernel packet area */ 



/* Macro expansion to interrupt-lnvoked C call to Ethernetinterrupt */ 
Call Hand! er(Enetlnterrupt) 
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A. 6. Parentheses 

For function calls, the parentheses "belong to" the call, so there is no space between function name and 
open parentheses. (There may be some inside the parentheses to make the argument list look nice.) When 
parentheses enclose the expression for a statement (if, for, etc.), the parentheses may be treated as 
belonging to the statement (since they arc syntactically required by the statement) so there is no space 
between the keyword and the expression. 

1f( (bytes » req->byteeount) <■ IO_MSG_BUFFER ) 

buffer ■ (char *) req->shortbuffer; 
else 

returh( req->bufferPointer ); 

Alternatively, parentheses may be treated as belonging to the expression, so there is a space between the 
keyword and the parenthesized expression. 

If (FuncA()) 

{ 

FuncB( (a ■ b) ■• ); 
return (Nil); 

> 
else 

{ 

FuncC( a, b, c ); 

return (ToSender); 
} 
Note that spaces arc used to separate operators from operands for clarity and may be selectively omitted to 
suggest precedence in evaluation. 

A.7. Messages 

Although V is a message-based system, most services arc available by calling standard routines, so 
programming at the "message level" is rarely necessary or desirable. However, the programming of new 
servers and the non-standard use of services or the use of messages within a program require message-level 
programming. The following conventions have been followed in V. 

Space to send or receive a message is declared of type Message, as defined in <Vcnviron.h>. Standard 
message formats, as defined in die V header files, declare each message format to be a new data type. Access 
to the space for die message is made by casting a pointer to the space to be of the type of the message format 
required. This guarantees that enough space is reserved even when a message format is not as large as the 
fixed-size message used by the kernel. The following illustrates this style. 

Read( fad, buffer, bytes ) 
File *fad; 
char *buffer; 
int bytes; 
/.• 

* Read the specified number of bytes into the buffer from the 

* file instance specified by fad*. The number of bytes read is 

* returned. 
•/ 

{ 

Message msg; 

register IoRequest *request ■ (IoRequest •) msg; 

register IoReply *reply ■ (loReply *) msg; 

register unsigned r, count; 

register char *buf; 
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for(::) 

request->requestcode ■ REAO_INSTANCE; 
pequest->f Held « fad->fneid; 
request->bufferPointer ■ buffer; 
request->bytecount ■ bytes; 
request->b1ocknumber ■ fad->b"lock; 

1f( Send( request, fad->f lleserver ) « ) 

fad->lastexcept1on ■ NONEXISTENTJ»ROCESS; 
return( ); 

1f( (r ■ rep1y->replycode) I- RETRY ) break; 



fad->1astexcept1on * r; 
count ■ rep1y->bytecount; 

1f( count <■ 10 MSG_BUFFER ) 

{ 

buf ■ (char •) request->shortbuffer; 

for( r » 0; r < count; ++r ) •buffer++ - *buf++; 

} 
return( count ); 
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— Appendix B — 
Installation Notes 



This document is intended to be an informal collection of information about the problems involved with 
installing and maintaining the V-Systcm software. The reader should be familiar with the V-Systcm as 
documented in the V-Systcm manuals, and with the Unix system used for development 

B.1. V-System Distribution 

The software should be distributed on a 1600 bpi tar format tape. Licensing information and tapes can be 
obtained from: 

Office of Technology Licensing 
105 Kncina Hall 
Stanford University 
Stanford, CA 94305 
(415)497-0651 

Please report any bugs you find, or improvements you make. All the software is under copyright protection, 
so you must get a license for any further distributions. Send comments on the software and documentation to 
the Arpanet address vbugs@SU-Pescadero.ARPA. New versions of the software may be released from 
time to time. 

'Hie first file on the tape is the entire source directory tree for the V-Systcm. Since the first implementation 
of the V-Systcm is for the Motorola MC68000, our versions of the 68000 C compiler, assembler, and linker are 
included as the second file on the tape. 

Note: This distribution has been booted only on Cadlinc and SUN MicroSystcms Workstations with 
MC68000s, not MC68Q10s, connected to a VAX by a 3Mb experimental Kthcrnct, using pup boot protocols. 
The next release will support the MC68010, 10 Mb standard Kthcrnct, and booting via the SMI network disk 
protocol. 

I*hc first step is to run tar x to extract the two files into directories in your file system wherever you have 
room. Remember to use the non-rewinding driver (e.g. /dev/rmtl2) or the mt f sf command if you want 
to read the second file. Throughout this document the V-Systcm patlinumcs will be referred to as 
V/somcthing, and the 68000 directory as sun/something. 

B.2. 68000 Tools 

We normally put Unc 68000 tools into /usr/sun. There arc a few other required directories that arc 
hardwired into a few of the makefiles, /usr/sun/includc is for the include (.h) files, and /usr/sun/lib is for 
libraries. The two major libraries that arc needed by some of the V-Systcm servers arc 1 1 bsf onts . a for the 
character fonts, and Hbgraphics.a for the SUN graphics primitives. We put binary versions of the 
stand-alone bootfilcs under /usr/sun/bootfilc, and put the V-Systcm commands under /usr/sun/Vboot. 

Many of the V-Systcm makefiles invoke the "ec68" command to compile and link. Be sure you have the 
latest version of the cc68 command, with the -V option. Connect to sun/sre/emd and do a make 
Install. You might want to edit the command file to put the commands in a place other than 
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/usr/local/bin. Next connect to sun/sre/graphics/iib and do a make 1 ns tall to make the graphics library. 
There will be a few warnings issued by the compiler which should be ignored. There arc manual entries for 
the 68000 software in /usr/sun/man68. • 

Our current V-Scrver software requires die CMU packet-filtering Ethernet driver for .4.1 or 4.2 Unix. Make 
sure the maximum packet size (MTU) is large enough to fit all the data bytes in a kernel packet plus the 
header. This driver and the associated higher-level software is available to people who have purchased Xerox 
1100 workstations in a separate distribution. 

Users who want to do 68000 development on a 68000-bascd Unix machine should be able to do so with a 
small amount of work. Please report your experiences back to us so that any software or information can be 
included in future releases. 

The Ipwatch family of programs under sun/diag/ip watch arc very useful to debug network problems. 
The enwatch program is used for 3Mb experimental Ethernet, and ecwateh for the 3Com interface. 
Others could be added easily. It keeps a record of the network packets of interest which can be written to a 
log file. Please include such a log file in all error reports. 

B. 3. Making the V-System 

Kdit the shell script under V/net 1ns tall to do the appropriate installation procedure for your system. 
We have it ftp the files to several other machines to automate the installation. This and a few other shell 
scripts arc assumed to be in the search path by the V-Systcm Makefiles. 'ITicsc sources arc in V/ tools and 
should be installed into some directory in the search path before making die rest of the system. Each 
directory contains a file called bulldflle which is processed by the buildmake program to produce a 
makefile. The buildf 11 e step includes conditional macro expansion. 

Change directory to V/I1bc and do a make 1nstall-1ncludes. This should copy the V-Systcm 
specific include files into /usr/sun/inciudc. Then do a make and then make 1 nstal 1 under this directory. 
This should result in 1 1 b V . a and teamroot . b being copied into Aisr/sun/Ub. 

Next change directory to V/servers, and do a make followed by a make install. The Vservcr is 
usually installed in /etc/Vserver and then a line is added to /etc/rc to start it up on system reboot. 
Give it a large argument on the command line, so that it can put useful information into the area printed by 
the Unix ps command. It should be run. as super-user, to allow it to check access protections correctly and 
sctuid to die correct user. 

The following arc the options available on die Vservcr: 

- d Debug flag for die major server code. 

~g Used if your system docs not have the simultaneous group feature (4.1a systems and 

beyond have this). 

-k Kernel debug. Used to debug the kernel simulator. 

= n Network debug. Used to produce a trace of network packets sent and received. 

-p Public mode. If this flag is set then broadcast GetPid requests arc answered. The default is 

to answer only requests directed spccificly at tliis particular host. There must be at least 
one Vservcr running the -p option on any given local network. 

Then change to the V/kernel directory and do a make followed by a make Install to compile the 
kernel and put the binary into /usr/sun/bootf 11 e. You may have to edit the makefile to configure the 
kernel for your I/O devices. The default is to support the Sun MicroSystcms Experimental 3M bit Kthcrnct 
interface. The 3Com Multibus EUicrnct Interface can also be supported. Other devices such as disk 
controllers will be supported in the next release. 
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Change directory to V/cmds and again do a make followed by a make install to compile all the 
commands. This takes a while, and uses the include files, libraries, and servers. 

Finally, change to the V/standalone directory. This directory is for bootstrapping and loading utilities. 
Currently the kernel and system team are loaded with the PUP EFTP protocol. The Vload program is 
compiled with several different flags. By default it will ask for a first team file, and possible the name of a 
kernel. By defining the symbol FIRST_TEAM a specific first team file can be used. 

It is also possible to use the V protocol itself to do the bootstrapping. In fact, some day we might put such a 
bootstrap into the PRO Ms to make the booting process easier. 
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68000 7 

BACKSPACE 199 

DEL 200 

DOWN ARROW 200 

home key 200 

LEFT ARROW 199 
LINEFEED 199 
RETURN 199 
RIGHT ARROW 199 
UP ARROW 200 

.Open 85 

[bin] 7,10 
[home] L0 
[public] 7,10 

Abort 104 

Abort Command 11,199 

Aborted 139 

Abs 93 

Active 219 

Add Context Name 157 

AddCall 118 

AddContcxtNamc 105 

Adding devices 223 

Adding kernel operations 223 

Addltcm 1.18 

AddLogicalNamc 105 

Addrcady 221,224 

AliasCotitcxtNamc 105 

Alien 222 

All 120 

Amaze 21 

ANSI 195 

Any 134 

Any Context J54 

Append Only 84,143 

Arrows 35 

Asynchronous communication 21 1 

AnKoixxriing M 

Awaiting-rcply 209 

AwailingRcply 97 

Backspace 36,40,194 
Backup 37 
Bad Address 139 
BadArgs 139 
Bad Block No 140 
Bad Buffer 140 
Bad Kyle Count 140 



Bad Process Priority 140 

Bad State 140 

Bare kernel mode 75, 104 

Beginning of Buffer 200 

Beginning of Line 11,199 

BcU 194 

Biopsy 21 

Bits 21,51 

Black 7 

Blank lines 227 

BtksInFile 88 

BlockPosition 88 

Blocks 143 

BtockSize 88 

Bit 95 

Boise 21 

Booting 7 

Bottom 36 

Break Process 11,199 

BufferEmpty 87 

Busy 140 

Cadiinc 8 

Calljnthandlcr 220 

alloc 95 

CD 8,21 

Center Window 16 

Crrcc 95 

Change Context 8,37 

Change Current Context 91 

Change Directory 8, 21 

ChangcDircctory 91 

Changcltcm 119 

Character Set 195 

Chcckcxccs 27 

Clear 96,194 

Clear Pad 194 

Clear To EOL 195 

Clear To EOS 194 

ClcarEof 87 

Click 15 

Client 115 

Clock 219 

Cose 85 

Color 116 - 

Compile command 75 

Concat 134 

Config Files 79 

Config.h 223 

Configuration 79 

Console 163 

Context 9,22,153 
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Context Directories 158 

Context Request 155 

Contexts 3 

Control 11, 199 

Convert^num 134 

Cooking 1.8,122,196 

Copy 39,95 

Copy_str 134 

Copydir 22 

Cp 22 

CR Input 122 

Create 75,104 

Create Instance 145, 195 

Create View 15 

Creatclnstance 85 

CreatePipcInstance 88 

CreateProccss 97 

CrealeSDF 117 

CreateScIcction Instance 114 

CrcateScssion 105 

CrcatcTcam 98 

CrcateVGT 120 

Creator 97 

CSnamc 153 

CSNU server 153 

CTRLA 200 

CTRL-a 1 1, L99 

CrRL-b 11. 199 

ClRL-d 11,199 

CTRL-c 11. 199 

CTRL-f 11,199 

CTRL-s 1J.199 

CrRL-h II, 199 

CTRL-k 11,200 

Cl'RL-l 200 

CI'RL-n 200 

CTRI.-p 200 

CTRI.-q 200 

CrRI,-t 11,200 

Cl'RL-u 11.200 

ClRL-w 11,200 

CIRL-y 200 

Cl*RL-z 12.200 

Current Context Invalid 140 

Cursor 122 

Cursor Backward 11,194,199 

Cursor Down 200 

Cursor Forward 11. 194, 199 

Cursor Motion 36 

Cursor Position 194 

Cursor Up 194,200 

Cursor Word Backward 12. 200 

Cursor Word Forward 12,200 

Dale 22 
Date 22 
Debug 17 
Debugger 29, 165 
DcfauUVicw 120 
Define 9,22 



Define Font 121 

DcfineSymbol 118 

DEL 194 

Delay 98.103,221 

Delete 36.39 

Delete Char 195 

Delete Character 11, 199 

Delete Character Backward 11, 199 

Delete Character Forward U, 199 

Delete Context Name 157 

Delete last Character 11, 199 

Delete Line 11,195 

Delete to Beginning of Line 11 

Delete to End of Line 1 1 

Delete to Start of Line 11 

Delete View 16 

Delete Window 41 

Delete Word 36,37 

Delete Word Back ward 11 

Delete Word Forward 12 

l")clelcContcxtNamc 105 

Dclelcltcm 118 

DeJctcSDF 117 

DclctcSymbol 119 

DclcteVGT 120 

Dcicxcc 27 

Destroy 22,104 

DestroyProcess 98 

Device Error 140 

Device server 161, 210. 218 

Device type 161 

DcviccCreatioiiTablc 223 

Devices 210 

DircctToCurrcnlContcxt 106 

DiscardOutput 122 

Display Hem 120 

Distributed operation 211. 222 

Do 27 

Duplicate Name 140 

Echo 22,122 
Editor 35 
EditSymbol 119 
End of Buffer 200 
End of File 12.140,200 
End of Line 11,199 
EndSymbol 118 
Eof 87 
Equal 134 
ErrorSlring 135, 141 
ESC-. 200 
ESC-. 200 

ESC-tlACKSHACB 200 

ESC-Dt'L 200 
ESC-b 12,200 
ESC-d 12,200 
ESC-f 12,200 
ESC-h 12,200 

rsc-i 200 

Escape 1L 199 
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Escape Sequences 194 
Ethernet 161 
Ethernet performance 218 
Event 115 
Event Request 196 
Example 124 
Exception Request 165 
Exception Server 165, 215 
ExceptionMcssage 215 
Exceptions 165, 215 
Exchange 39 
Exec 7,197 
Exec Control 7,16 
ExecProg 107 
Executive 7,15.75,104 
Exit 104 
Expansion Depth 17 

FAppcnd 83,145 
FCreato 83, 144 
FDircctory 145 
FExccutc 145 
Fields 127 
File Access 37 
Rlc Modes 83. 144 
file Types 84,143 
FilcExccption 88 
Hlcld 90 
FilcScrvcr 90 
HIcTypc 90 
Filled Rectangle 116 
FmdSclcctcdObjcct 120 
Fixed length 84, 144 
Ftxcd Menu 38 
Hush 86 
HVtodify 83,145 
Font 121 
Forget 37 
Forward 98 
Forwarder 98 
FRcad 83,144 
Free 95 
Fschcck 59 
[■'Session 145 

General Line 116 
Get Context Id 155 
Get Context Name 156 
Get I lie 41 
Gel I mIo Name 156 
GctContcxtld 106 
GctContcxtNamc 106 
GclEvcnt 124 
GclFilcNamc 106 
GctGraphicsEvcnt 123 
GctGraphicsSlatus 123 
GctMorcMallocSpacc 96 
GctPid 99.222 
GetTcamRoot 99 
GctTcamSize 99 



GctTimc 99 
GeiTTY 123 
GiveToMalloc 96 
Go To 39 
Grab 39 
Graphics 115 
Graphics Commands 16 

Help 22 

Hex„value 134 

History 12 

Hit Detection 120 

Horizontal line 116 

Horizontal Reference Line 117 

I/O 83 

I/O Protocol 115. 143. 193. 210 

Idcmpotent 102 

Idle process 220 

Ignored 194 

Illegal Request 140 

Index 194 

Initl-xccptionServcr 165 

Initial priority 75 

Initial process 75 

Initial stack 75,223 

Initialization 210 

InquircCall 118 

Inquire! tern 118 

Insert 37 

Insert Char 195 

Insert Line 195 

Insert I -inefced 37 

Insert With EighUi Bit Set 200 

Installation 233 

interactive 84. 90, 144 

Internal Error 140 

Internet Server 22 

Interprocess communication 210 

I ntcrmpt disable time 218 

Interrupt masking 219 

Interrupts 220 

Invalid Context 140 

Invalid File Id 140 

Invalid Mode 140 

Inverse Video 195 

IO Break 140 

IO Protocol 72 

Iptclnct 22 

Iptn 22 

Iris 116 

Item 115.116 

Item Type 116 

Kernel arguments 223 
Kernel configuration 223 
Kernel Operations 213 
Kernel stack 219 
KcrnclTimcout 140 
Kernel timings 217 
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Kernel traps 220 

Kcrnelops 223 

Kill 37 

Kill Break 11,199 

KM Buffer 38 

Kill Input Buffer 200 

Kill Program 196 

Kill Region 40 

Kill to End of Line 200 

Kill Word Backward 200 

Kill Word Forward 200 

Killprog 27 

U68 29 

Left Button 18,38 

Lcft+Middlc Buttons 18 

Lcft+ Right Buttons 18 

LF Output 122 

LibV.a 75 

Line 36, 116 

Line Buffer 122 

I inc Editing 1 1 

Line- Editing 15, 122 

Linefeed 37 

Linking 75 

list Type 120 

Ustdir 23 

Loader 76 

Loading Nonstandard Kernels 67 

LoadNcwTeam 108 

LoadProg 107 

LoadTcam 108 

Local Name Server 8 

Login 9,23 

lx>gin Context 154 

Logout 10,23 

I .ongjmp 135 

Lower 135 

Make Bottom 16 

Make Top 16 

Malloc 75,95 

Mark 40 

Math 93 

Memory management 209 

Menu 121,127 

Menu. View Manager 15 

Merge Windows 41 

Message Formal Conventions 139 

Message primitives 221 

Messages 2J0 

Middle Button 18,38 

Middle* Right Buttons 18 

Mode 145 

Mode Not Supported 141 

Modes 83,144 

Modify File 150.196 

Modify Pad 123 

Monasteries 75 

Motorola 68000 215 



Mouse 15. 18. 38, 162 
Mouse emulation 18 
Mouse Event Request 196 
Mouse Status Request 196 
Move Edges 16 
Move Edges + Object 16 
Move Viewport 16 
MovcFrom 99 
MovcTo 100 
MulU Block 84,144 

Name Request 154 

Names 227 

Naming 210 

Naming Protocol 153 

New Line 194 

Ncwterm 23 

Next Line 194 

NModifyRle 150 

No 40 

No Memory 141 

NoPDs 141 

No Permission 141 

No Process Descriptors 141 

No Server Resources 141 

NoCursor 122 

Nonexistent Process 141 

Nonexistent Session 141 

Not Awaiting Reply 141 

Not Found 14.1 

Not Readable 141 

NotWritcablc 141 

NQucryRlc 150 

NRcad Descriptor 159 

NUL 194 

NulljJtr 135 

Number of devices 223 

Number of processes 223 

Number of teams 223 

Numeric 93 

NWrite Descriptor 159 

Object Descriptors 158 
OK 139 
Open 84 
OpcnFile 85,122 
OpenJp 89 
OpcnPad 122.195 
OpcnPup 89 
OpcnSlr 90 
OpcnTcp 88 
Outline 117 

Pad 15 

Pad Escape Sequences 194 

PadFindPoint 124 

l*agc Down 36 

Page Up 36 

l'agcd output mode 17 

Pagcmode 23 
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PagcOutput 122 

PagcOutputEnablc 122 

ParscLine 109 . 

Pcr-Process Area 77,209 

Point 116 

Pointer 116 

Popup 121 

Power Failure 141 

Previous Word 12,200 

PrintError 136 

Printf 83 

PrintFile 91 

Priority 219.221 

Process 97,209 

Process creation 221 

Process descriptor 2.19 

Process destruction 221 

Process identifier 209 

Process management 209 

Process switching 220 

Processes 219 

Processor allocation 209, 221 

PROM 72 

PROM monitor 104 

Protocol 139 

Public 183 

Public Context 154 

Pull Apart 41 

PUP 24 

Pwd 9,22 

Qsort 135 

Query File 150,196 

Query Instance 146, 195 

Query Replace 39, 40 

Querycxcc 27 

Query Kernel 100 

QucryPad 123 

Query PadSi/c 123 

QucryPrpccssSlaic 100, 215 

Query WorkstationCon fig 79 

Quit 36 

Quote 37 

Quote Character 200 

Rand 93 
Raster 117. 1L8 
Raw 122 

Re-Display Input 200 
Read 87 

Read Descriptor 159* 
Read Instance 147. 196 
Readable 84, 143 
RcadProcessStale 100. 215 
Ready 104,209 
Real-time 209 
Rcalloc 95 
RcccivcSpccific 101 
RoccivcWithSegmcnt 100 
Rectangle 116 



Redisplay 39 
Redraw 17,36 
RedrawPad 124 
Reference Line 117 
Region 40 
Register Handler 165 
RcgislerScrver 113 
Release Input Buffer 199 
Release Instance 147, 196 
Release Instance 86 
Relocation 75 

Remote program execution 10 
RcmotcExccutc 108 
Removcl'ile 90 
Removcrcady 221.224 
Repeat Search 39 
Replacement String 40 
Reply 10 1 
Reply code 139 . 
ReplyWiihScgmcnt 101 
Report Click 122 
Report Transition 1.22 
Request code 139 
Request Message Formats 145 
R cqucst Not Su pportcd 1 4 1 
RcrcadMsg 101 
ResctTIT 123 
Resynch 86 
Retry 141 
Return 37,194 
Reverse Index 195 
Reverse Search 39,40 
Right Button 18,38 
Root process 223 
RunProgram 108 

Same Team 101 

Sanity 42 

Save 37 

Scheduling 219 

Scroll 36,39 

Scroll Region 195 

SDI' 115 

Search 38,39,40 

Searching 38 

Seek 86 

ScekBlock 88 

Segment 102 

Segments 210 

Select 41 

Selected Vertical Reference Line 117 

SclcctPad 123 

Send 101,222 

Send- Receive- Reply 217 

Serial 23 

Serial line 162 

Server Not Responding 141 

Services 139 

Session 23,73 

Sessions 9 
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Set Break Process 149,196 

Set Instance Owner 149 

Set Mark 40 

Set Prompt 149 

SctlJrcakProccss 90,197 

SoilnstanceOwner 91 

Setjmp 135 

SctPid 102 

SctTcamPriority 102 

SctTcamSizc 103 

SetTimc 103 

SctUpArgumcnts 109 

SctVgtBanner 197 

Shell 7 

Shiain 194 

ShtaOut 194 

Shift Jcft 135 

Show 24 

Sibling 116 

Size 135 

Sleep 133 

SMI 7.8 

Space Bar 39 

Special States 36 

SpcciaiClosc 85 

Spline 117.118 

Srand 93 

Slack 209 

Slack overflow 75 

Start of Line 11,199 

Startcxcc 27 

Stipple 116 

Stream 84, 143 

Structured Display f"ilc 115 

STS hardware environment 200 

STS input editing 199 

Style 227 

Suicide 104 

Supervisor mode 219 

Swab % 

Switch 220 

Switch Input 1% 

Symbol 115 

Synchronization 219 

Tab 37,39,194 

Team 209 

Team descriptor 219 

Team Root Message 76 

TcamRool 76 

Teams 209.219 

Telnet 24 

Terminal Emulator 194 

TcrminaicScssion 106 

Tcstexccpt 24 

Text 36,115,116,117 

Time 73 

Time management 210 

Time primitives 221 

Timckcrncl 24 



Timeout 141 
Toggle Grid 17 
Top 36 
Tops-20 7 

Transparent operation 211 
Transpose 11 
Transpose Characters 200 
Transpose Words 200 
Trap.c 223 
Type 24,84, 116 
TypeData 116 
Types 143 

Un-Kill 200 

Undcfine 9 

Undo 40 

Unix 7, 10, 25, 71, 73, 183 

UnrcgistcrScrver 113 

Upper 135 

V server 9. 10, 183 

ValidPid 103 

ValidProgram 109 

Variable Block 84.144 

Vax 25 

Vcd 24,35 

Vcnviron.li 75,139 

Vertical Line 116 

Vertical Reference line 117 

VcthcmcLh 161 

Vcxccptions.h L65. 215 

VGT 1.15. 119. 193 

VGTS 7, 15. 18, 29 

Vgts.h 116,120.121 

Vgtscxcc 7 

View 16,115. 119. 193 

View Manager 7. 15, 196 

View Manager Menu 15 

Vio.h 143 

Vioprotocol.h 145 

Virtual Graphics Terminal 119 

Visit 37 

Vload 63.76 

Vmousah 162 

Wakcup 103 
Word 36 
Workstation 209 
Write 37.87 
Write I3escriptor 159 
Write Instance 148, 1% 
Write Region 40 
Wriicablc 84,143 
WritcKernclPackct 222 
WritcProccssStatc 103 
Writcshort Instance 1% 

Xmax 116 
Xmin 116 
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Yale 22.117 

Yank 37 

Yank to window 4L 

Yes 40 

Ymax 116 

Ymin 116 



Zero 96.116 
Zoom 16 
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